The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
Publish Twenty app skills as a portable Agent Skills collection (skills.sh) (#25913)
martmull330cf9c39d14
diff --git a/.cursor/skills/syncable-entity-builder-and-validation/SKILL.md b/.claude/skills/syncable-entity-builder-and-validation/SKILL.mdsimilarity index 96%rename from .cursor/skills/syncable-entity-builder-and-validation/SKILL.mdrename to .claude/skills/syncable-entity-builder-and-validation/SKILL.mdindex e406611ebef..40daab6fbee 100644--- a/.cursor/skills/syncable-entity-builder-and-validation/SKILL.md+++ b/.claude/skills/syncable-entity-builder-and-validation/SKILL.md@@ -1,6 +1,6 @@---name: syncable-entity-builder-and-validation-description: Create validation logic and migration action builders for syncable entities in Twenty. Use when implementing business rule validation, uniqueness checks, foreign key validation, or building workspace migration actions for syncable entities. Validators never throw and never mutate.+description: Contributing to the Twenty codebase itself (twentyhq/twenty server internals), not for building apps on top of Twenty. Create validation logic and migration action builders for syncable entities in Twenty. Use when implementing business rule validation, uniqueness checks, foreign key validation, or building workspace migration actions for syncable entities. Validators never throw and never mutate.---# Syncable Entity: Builder & Validation (Step 3/6)diff --git a/.cursor/skills/syncable-entity-cache-and-transform/SKILL.md b/.claude/skills/syncable-entity-cache-and-transform/SKILL.mdsimilarity index 96%rename from .cursor/skills/syncable-entity-cache-and-transform/SKILL.mdrename to .claude/skills/syncable-entity-cache-and-transform/SKILL.mdindex b8800ffae80..7d1844aaea3 100644--- a/.cursor/skills/syncable-entity-cache-and-transform/SKILL.md+++ b/.claude/skills/syncable-entity-cache-and-transform/SKILL.md@@ -1,6 +1,6 @@---name: syncable-entity-cache-and-transform-description: Create cache services and transformation utilities for syncable entities in Twenty. Use when implementing entity-to-flat conversions, input DTO transpilation to universal flat entities, or cache recomputation for syncable entities.+description: Contributing to the Twenty codebase itself (twentyhq/twenty server internals), not for building apps on top of Twenty. Create cache services and transformation utilities for syncable entities in Twenty. Use when implementing entity-to-flat conversions, input DTO transpilation to universal flat entities, or cache recomputation for syncable entities.---# Syncable Entity: Cache & Transform (Step 2/6)diff --git a/.cursor/skills/syncable-entity-integration/SKILL.md b/.claude/skills/syncable-entity-integration/SKILL.mdsimilarity index 96%rename from .cursor/skills/syncable-entity-integration/SKILL.mdrename to .claude/skills/syncable-entity-integration/SKILL.mdindex 563ef94298f..7f9bdfdae76 100644--- a/.cursor/skills/syncable-entity-integration/SKILL.md+++ b/.claude/skills/syncable-entity-integration/SKILL.md@@ -1,6 +1,6 @@---name: syncable-entity-integration-description: Wire syncable entity services into NestJS modules, create service layer and resolvers for Twenty entities. Use when registering builders, validators, and action handlers in modules, creating business services, or exposing entities via GraphQL API with proper exception handling.+description: Contributing to the Twenty codebase itself (twentyhq/twenty server internals), not for building apps on top of Twenty. Wire syncable entity services into NestJS modules, create service layer and resolvers for Twenty entities. Use when registering builders, validators, and action handlers in modules, creating business services, or exposing entities via GraphQL API with proper exception handling.---# Syncable Entity: Integration (Step 5/6)diff --git a/.cursor/skills/syncable-entity-runner-and-actions/SKILL.md b/.claude/skills/syncable-entity-runner-and-actions/SKILL.mdsimilarity index 96%rename from .cursor/skills/syncable-entity-runner-and-actions/SKILL.mdrename to .claude/skills/syncable-entity-runner-and-actions/SKILL.mdindex ad5632457b0..cdfa6f0eceb 100644--- a/.cursor/skills/syncable-entity-runner-and-actions/SKILL.md+++ b/.claude/skills/syncable-entity-runner-and-actions/SKILL.md@@ -1,6 +1,6 @@---name: syncable-entity-runner-and-actions-description: Implement action handlers for executing workspace migrations in Twenty. Use when creating database operations for syncable entities, implementing universal-to-flat entity transpilation, or handling create/update/delete actions in the runner layer.+description: Contributing to the Twenty codebase itself (twentyhq/twenty server internals), not for building apps on top of Twenty. Implement action handlers for executing workspace migrations in Twenty. Use when creating database operations for syncable entities, implementing universal-to-flat entity transpilation, or handling create/update/delete actions in the runner layer.---# Syncable Entity: Runner & Actions (Step 4/6)diff --git a/.cursor/skills/syncable-entity-testing/SKILL.md b/.claude/skills/syncable-entity-testing/SKILL.mdsimilarity index 97%rename from .cursor/skills/syncable-entity-testing/SKILL.mdrename to .claude/skills/syncable-entity-testing/SKILL.mdindex 2099e9e04c4..1a67cbf0b06 100644--- a/.cursor/skills/syncable-entity-testing/SKILL.md+++ b/.claude/skills/syncable-entity-testing/SKILL.md@@ -1,6 +1,6 @@---name: syncable-entity-testing-description: Create comprehensive integration tests for syncable entities in Twenty. Use when writing integration tests for metadata entities, covering validator exceptions, input transpilation errors, and CRUD operations. Tests are MANDATORY for all syncable entities.+description: Contributing to the Twenty codebase itself (twentyhq/twenty server internals), not for building apps on top of Twenty. Create comprehensive integration tests for syncable entities in Twenty. Use when writing integration tests for metadata entities, covering validator exceptions, input transpilation errors, and CRUD operations. Tests are MANDATORY for all syncable entities.---# Syncable Entity: Integration Testing (Step 6/6 - MANDATORY)diff --git a/.cursor/skills/syncable-entity-types-and-constants/SKILL.md b/.claude/skills/syncable-entity-types-and-constants/SKILL.mdsimilarity index 95%rename from .cursor/skills/syncable-entity-types-and-constants/SKILL.mdrename to .claude/skills/syncable-entity-types-and-constants/SKILL.mdindex fc2eb1c7d4a..1c7bab40396 100644--- a/.cursor/skills/syncable-entity-types-and-constants/SKILL.md+++ b/.claude/skills/syncable-entity-types-and-constants/SKILL.md@@ -1,6 +1,6 @@---name: syncable-entity-types-and-constants-description: Define types, entities, and central constant registrations for syncable entities in Twenty's workspace migration system. Use when creating new syncable entities, defining TypeORM entities, flat entity types, or registering in central constants (ALL_ENTITY_PROPERTIES_CONFIGURATION_BY_METADATA_NAME, ALL_ONE_TO_MANY_METADATA_RELATIONS, ALL_MANY_TO_ONE_METADATA_FOREIGN_KEY, ALL_MANY_TO_ONE_METADATA_RELATIONS).+description: Contributing to the Twenty codebase itself (twentyhq/twenty server internals), not for building apps on top of Twenty. Define types, entities, and central constant registrations for syncable entities in Twenty's workspace migration system. Use when creating new syncable entities, defining TypeORM entities, flat entity types, or registering in central constants (ALL_ENTITY_PROPERTIES_CONFIGURATION_BY_METADATA_NAME, ALL_ONE_TO_MANY_METADATA_RELATIONS, ALL_MANY_TO_ONE_METADATA_FOREIGN_KEY, ALL_MANY_TO_ONE_METADATA_RELATIONS).---# Syncable Entity: Types & Constants (Step 1/6)diff --git a/.cursor/Dockerfile b/.cursor/Dockerfiledeleted file mode 100644index a06a432578e..00000000000--- a/.cursor/Dockerfile+++ /dev/null@@ -1,34 +0,0 @@-FROM ubuntu:22.04--ENV DEBIAN_FRONTEND=noninteractive--RUN apt-get update && apt-get install -y \- curl \- git \- make \- build-essential \- postgresql-client \- docker.io \- && rm -rf /var/lib/apt/lists/*--# Install nvm (project recommends nvm + .nvmrc for consistent Node versions)-ENV NVM_DIR=/usr/local/nvm-RUN mkdir -p $NVM_DIR \- && curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash--SHELL ["/bin/bash", "-c"]--# Copy .nvmrc so nvm install picks up the right version-COPY .nvmrc /tmp/.nvmrc--# Install Node.js from .nvmrc, enable Corepack, and symlink binaries-# so they're available on PATH without hardcoding a version-RUN . $NVM_DIR/nvm.sh \- && nvm install $(cat /tmp/.nvmrc) \- && nvm alias default $(cat /tmp/.nvmrc) \- && corepack enable \- && BIN_DIR=$(dirname $(nvm which default)) \- && ln -sf $BIN_DIR/node /usr/local/bin/node \- && ln -sf $BIN_DIR/npm /usr/local/bin/npm \- && ln -sf $BIN_DIR/npx /usr/local/bin/npx \- && ln -sf $BIN_DIR/corepack /usr/local/bin/corepackdiff --git a/.cursor/environment.json b/.cursor/environment.jsondeleted file mode 100644index 55a886c302b..00000000000--- a/.cursor/environment.json+++ /dev/null@@ -1,10 +0,0 @@-{- "install": "yarn install",- "start": "(sudo service docker start || service docker start || true) && bash packages/twenty-utils/setup-dev-env.sh && npx nx database:reset twenty-server",- "terminals": [- {- "name": "Development Server",- "command": "yarn start"- }- ]-}diff --git a/.cursor/rules/README.mdc b/.cursor/rules/README.mdcdeleted file mode 100644index c725458435e..00000000000--- a/.cursor/rules/README.mdc+++ /dev/null@@ -1,141 +0,0 @@-----description: Twenty CRM development rules and best practices-globs: []-alwaysApply: true-----# Twenty Development Rules--This directory contains Twenty's development guidelines and best practices in the modern Cursor Rules format (MDC). These rules are automatically applied based on file patterns and provide context-aware guidance to AI assistants.--## Rules Overview--### Core Guidelines-- **architecture.mdc** - Project overview, technology stack, and infrastructure setup (Always Applied)-- **nx-rules.mdc** - Nx workspace guidelines and best practices (Auto-attached to Nx files)-- **server-migrations.mdc** - Upgrade command guidelines (instance commands and workspace commands) for `twenty-server` (Auto-attached to server entities and upgrade command files)-- **creating-syncable-entity.mdc** - Comprehensive guide for creating new syncable entities (with universalIdentifier and applicationId) in the workspace migration system (Agent-requested for metadata-modules and workspace-migration files)--### Code Quality-- **typescript-guidelines.mdc** - TypeScript best practices and conventions (Auto-attached to .ts/.tsx files)-- **code-style.mdc** - General coding standards and style guide (Auto-attached to code files)-- **file-structure.mdc** - File and directory organization patterns (Auto-attached to config files)--### React Development-- **react-general-guidelines.mdc** - Core React development principles (Auto-attached to React files)-- **react-state-management.mdc** - State management approaches with Jotai (Auto-attached to state files)--### Testing & Quality-- **testing-guidelines.mdc** - Testing strategies and best practices (Auto-attached to test files)--### Internationalization-- **translations.mdc** - Translation workflow and i18n setup (Auto-attached to locale files)--## How Rules Work--### Automatic Attachment-Rules are automatically included in your AI context based on file patterns (globs). When you work on TypeScript files, the TypeScript guidelines are automatically loaded.--### Manual Reference-You can manually reference any rule using the `@ruleName` syntax:-- `@nx-rules` - Include Nx-specific guidance-- `@react-general-guidelines` - Load React best practices-- `@testing-guidelines` - Get testing recommendations-- `@creating-syncable-entity` - Guide for creating new syncable entities--### Rule Types Used-- **Always Applied** - Loaded in every context (architecture.mdc, README.mdc)-- **Auto Attached** - Loaded when matching file patterns are referenced-- **Agent Requested** - Available for AI to include when relevant-- **Manual** - Only included when explicitly mentioned--## Development Commands--### Frontend Commands-```bash-# Testing-npx nx test twenty-front # Run unit tests-npx nx storybook:build twenty-front # Build Storybook-npx nx storybook:test # Run Storybook tests--# Development-npx nx lint:diff-with-main twenty-front # Lint files changed vs main (fastest)-npx nx lint:diff-with-main twenty-front --configuration=fix # Auto-fix changed files-npx nx lint twenty-front # Lint all files (slower)-npx nx typecheck twenty-front # Type checking-npx nx run twenty-front:graphql:generate # Generate GraphQL types-```--### Backend Commands-```bash-# Database-npx nx database:reset twenty-server # Reset database-npx nx run twenty-server:database:init:prod # Initialize database-npx nx run twenty-server:database:migrate:prod # Run migrations--# Development-npx nx run twenty-server:start # Start the server-npx nx lint:diff-with-main twenty-server # Lint files changed vs main (fastest)-npx nx lint:diff-with-main twenty-server --configuration=fix # Auto-fix changed files-npx nx run twenty-server:lint # Lint all files (slower)-npx nx run twenty-server:typecheck # Type checking-npx nx run twenty-server:test # Run unit tests-npx nx run twenty-server:test:integration:with-db-reset # Run integration tests--# Upgrade commands (instance + workspace)-npx nx run twenty-server:database:migrate:generate --name <name> --type <fast|slow>-```--## Usage Guidelines--### For Developers-- Rules are automatically applied based on file context-- Check rule descriptions to understand when they're activated-- Use manual references (`@ruleName`) for additional context-- Keep rules updated as the codebase evolves--### For AI Assistants-- Rules provide consistent guidance across conversations-- Use rule context to maintain coding standards-- Reference specific rules when making recommendations-- Apply rule principles in code suggestions and reviews--## Contributing to Rules--### Adding New Rules-1. Create a new `.mdc` file in this directory-2. Include proper metadata headers with description and globs-3. Write clear, actionable guidelines with examples-4. Test the rule with relevant file patterns-5. Update this README if needed--### Updating Existing Rules-1. Modify the rule content while preserving metadata-2. Test changes with affected file patterns-3. Ensure consistency with other rules-4. Update examples and best practices as needed--## Rule Format Reference--Each rule file uses the MDC format with metadata:--```markdown-----description: Brief description of the rule's purpose-globs: ["**/*.ts", "**/*.tsx"] # File patterns for auto-attachment-alwaysApply: false # Whether to always include this rule------# Rule Title--Rule content in Markdown format...-```--## Migration from Legacy Format--The rules have been migrated from the legacy `.md` format to the modern `.mdc` format, providing:-- Better context awareness through file pattern matching-- Improved organization with metadata headers-- More flexible rule application strategies-- Enhanced integration with Cursor's AI features--For the most up-to-date version of these guidelines, always refer to the files in this directory.diff --git a/.cursor/rules/architecture.mdc b/.cursor/rules/architecture.mdcdeleted file mode 100644index 8b060badc0c..00000000000--- a/.cursor/rules/architecture.mdc+++ /dev/null@@ -1,30 +0,0 @@-----description: Twenty CRM architecture overview - monorepo structure, tech stack, and development principles-globs: []-alwaysApply: true------# Twenty Architecture--## Tech Stack-- **Frontend**: React 18, TypeScript, Jotai, Styled Components, Vite-- **Backend**: NestJS, TypeORM, PostgreSQL, Redis, GraphQL-- **Monorepo**: Nx workspace with yarn--## Package Structure-```-packages/-├── twenty-front/ # React app-├── twenty-server/ # NestJS API-├── twenty-ui/ # Shared components-├── twenty-shared/ # Common types/utils-└── twenty-emails/ # Email templates-```--## Key Principles-- **Functional components only** (no classes)-- **Named exports only** (no default exports)-- **Types over interfaces** (except for extending third-party)-- **String literals over enums** (except GraphQL)-- **No 'any' type allowed**-- **Event handlers over useEffect** for state updatesdiff --git a/.cursor/rules/changelog-process.mdc b/.cursor/rules/changelog-process.mdcdeleted file mode 100644index 35d527397ba..00000000000--- a/.cursor/rules/changelog-process.mdc+++ /dev/null@@ -1,326 +0,0 @@-----description: Process and guidelines for creating release changelogs for Twenty CRM-globs: ["**/releases/*.mdx", "**/releases/**"]-alwaysApply: false-----# Twenty Release Changelog Process--Complete guide for creating release changelogs, including codebase research, file structure, and content guidelines.--## Prerequisites--Before starting, gather the following information:--### Required Information--**Version Number**: `{VERSION}` (e.g., 1.9.0, 2.0.0, 2.1.0)--**Release Date**: Use today's date in format: YYYY-MM-DD--### Changes/Features to Document--List the features and changes to include in this release:--1. **Feature Name**: ______________________________- - Brief description: ______________________________- - Related area (workflow, UI, backend, etc.): ______________________________--2. **Feature Name**: ______________________________- - Brief description: ______________________________- - Related area: ______________________________--3. **Feature Name**: ______________________________- - Brief description: ______________________________- - Related area: ______________________________--## Codebase Research Guide--If feature descriptions are not provided or need enhancement, research the codebase:--### Where to Look--**For Workflow Features:**-- Frontend: `packages/twenty-front/src/modules/workflow/`-- Backend: `packages/twenty-server/src/modules/workflow/`-- Components: `packages/twenty-front/src/modules/workflow/components/`--**For UI/UX Changes:**-- Components: `packages/twenty-front/src/modules/ui/`-- Layout: `packages/twenty-front/src/modules/layout/`-- Design system: `packages/twenty-ui/src/`--**For Backend/API Features:**-- Server modules: `packages/twenty-server/src/modules/`-- Entities: `packages/twenty-server/src/entities/`-- Services: Look for `*.service.ts` files--**For Database/ORM Changes:**-- Instance commands (fast/slow): `packages/twenty-server/src/database/commands/upgrade-version-command/`-- Legacy TypeORM migrations: `packages/twenty-server/src/database/typeorm/`-- Entities: `packages/twenty-server/src/entities/`--### Research Commands--```bash-# Find recent merged PRs (adjust date as needed)-gh pr list --search "merged:>2025-10-01" --limit 50 --state merged--# View recent commits-git log --since="2 weeks ago" --oneline --no-merges--# View commits between releases (replace with actual release tags)-git log v1.7.0..v1.8.0 --oneline--# Search for specific feature keywords in code-grep -r "iterator" packages/twenty-front/src/modules/workflow/-grep -r "bulk select" packages/twenty-front/src/modules/workflow/--# Find recent changes in specific directory-git log --since="2 weeks ago" --oneline -- packages/twenty-front/src/modules/workflow/-```--### Using Codebase Search--Use the AI codebase search to find:-- "How does the workflow iterator node work?"-- "Where is bulk select implemented for workflows?"-- "What changes were made to the search node limit?"--## Step-by-Step Process--### 1. Setup Git Branch--**IMPORTANT**: Always start from an up-to-date main branch to avoid merge conflicts and ensure the changelog is based on the latest code.--```bash-cd /Users/thomascolasdesfrancs/code/twenty-git checkout main-git pull origin main-git checkout -b {VERSION}-```--Replace `{VERSION}` with the actual version number (e.g., `1.9.0`)--⚠️ **Do this first** before making any file changes. This ensures your branch is based on the latest main.--### 2. Create File Structure--**Create changelog file:**-- Path: `packages/twenty-website/src/content/releases/{VERSION}.mdx`-- Example: `packages/twenty-website/src/content/releases/1.9.0.mdx`--**Create image folder:**-- Path: `packages/twenty-website/public/images/releases/{MINOR_VERSION}/`-- Example for version 1.9.0: `packages/twenty-website/public/images/releases/1.9/`-- Example for version 2.0.0: `packages/twenty-website/public/images/releases/2.0/`--```bash-# Create the image folder-mkdir -p packages/twenty-website/public/images/releases/{MINOR_VERSION}-```--### 3. Move Illustration Files--**Source:** `/Users/thomascolasdesfrancs/Downloads/🆕`--**Destination:** `packages/twenty-website/public/images/releases/{MINOR_VERSION}/`--**Naming Convention:** `{VERSION}-descriptive-name.webp`--Examples:-- `1.9.0-feature-name.webp`-- `1.9.0-another-feature.webp`--```bash-# Move and rename source files, then convert to webp if needed-cp ~/Downloads/🆕/source-file.png packages/twenty-website/public/images/releases/{MINOR_VERSION}/{VERSION}-feature-name.png-cd packages/twenty-website && node scripts/convert-png-to-webp.mjs-```--### 4. Research Features (if needed)--If descriptions are not provided:-1. Use the research commands above to find recent PRs and commits-2. Search the codebase for feature-related code-3. Read PR descriptions for context-4. Check component comments and documentation--### 5. Write Changelog Content--Create the MDX file with this structure:--```markdown-----release: {VERSION}-Date: {YYYY-MM-DD}------# Feature 1 Name--Short description explaining what the feature does and why it's useful. Keep it user-focused and concise (1-2 sentences).----# Feature 2 Name--Another short description of the second feature.----# Feature 3 Name--Description of the third feature.---```--**Style Guidelines:**-- Use H1 (`#`) for feature names-- Keep descriptions to 1-2 sentences-- Focus on user benefits, not technical implementation-- Use active voice-- Start with what the user can now do-- **NEVER mention the brand name "Twenty"** in changelog text - use "your workspace", "the platform", or similar neutral references instead--**Reference Previous Changelogs:**-- Check `packages/twenty-website/src/content/releases/` for examples-- Recent releases: 1.7.0.mdx, 1.6.0.mdx, 1.5.0.mdx--### 6. Review--Open the changelog file for review:-```bash-# Open in Cursor-cursor packages/twenty-website/src/content/releases/{VERSION}.mdx--# Open image folder to verify illustrations-open packages/twenty-website/public/images/releases/{MINOR_VERSION}-```--Review checklist:-- [ ] Version number is correct in frontmatter-- [ ] Date is today's date-- [ ] All features are documented-- [ ] Image paths are correct-- [ ] Image files exist in the folder-- [ ] Descriptions are clear and user-focused-- [ ] Spelling and grammar are correct--### 7. Present Changelog for User Approval--**IMPORTANT**: Before committing and creating the PR, always show the complete changelog content to the user and wait for explicit approval.--**What to show:**-1. Display the full MDX content of the changelog file-2. Confirm that illustration files were moved to the correct location-3. List the image file names and paths--**What to say:**-```-I've created the changelog for version {VERSION}. Here's the content for your review:--[Show full MDX content]--Images moved to:-- packages/twenty-website/public/images/releases/{MINOR_VERSION}/{VERSION}-feature-1.webp-- packages/twenty-website/public/images/releases/{MINOR_VERSION}/{VERSION}-feature-2.webp--Please review the content. Once you approve, I'll commit the changes and create the pull request.-```--**Wait for user approval before proceeding to step 8.**--Possible user responses:-- "Looks good" / "Approve" / "Create the PR" → Proceed to step 8-- Requests changes → Make the requested edits, then show content again-- Asks questions → Answer them, then wait for approval--### 8. Commit Changes--```bash-# Check status-git status--# Add files-git add packages/twenty-website/src/content/releases/{VERSION}.mdx-git add packages/twenty-website/public/images/releases/{MINOR_VERSION}/--# Commit-git commit -m "Add {VERSION} release changelog"--# Push branch-git push -u origin {VERSION}-```--### 9. Create Pull Request--```bash-# Create PR using GitHub CLI-gh pr create \- --title "Release {VERSION}" \- --body "## Release {VERSION}--This release includes:--- Feature 1-- Feature 2-- Feature 3--Changelog file: \`packages/twenty-website/src/content/releases/{VERSION}.mdx\`-Release date: {DATE}" \- --base main \- --head {VERSION}-```--Or visit: `https://github.com/twentyhq/twenty/pull/new/{VERSION}`--## File Naming Conventions--### Changelog Files-- **Format**: `{MAJOR}.{MINOR}.{PATCH}.mdx`-- **Convention**: One file per complete version-- **Examples**: `1.6.0.mdx`, `1.7.0.mdx`, `2.0.0.mdx`-- **Location**: `packages/twenty-website/src/content/releases/`--### Image Folders-- **Format**: `{MAJOR}.{MINOR}/`-- **Convention**: One folder per minor version (shared across patches)-- **Examples**: `1.6/`, `1.7/`, `2.0/`-- **Location**: `packages/twenty-website/public/images/releases/`--### Image Files-- **Format**: `{VERSION}-descriptive-name.webp`-- **Convention**: Kebab-case descriptive names-- **Examples**:- - `1.8.0-workflow-iterator.webp`- - `1.8.0-bulk-select.webp`- - `1.9.0-new-feature.webp`--## Quick Reference Template--Copy and fill this for each release:--```-VERSION: ___________-DATE: ___________-MINOR_VERSION: ___________--Features to document:-1. ___________________________-2. ___________________________-3. ___________________________--Branch name: {VERSION}-Changelog path: packages/twenty-website/src/content/releases/{VERSION}.mdx-Images path: packages/twenty-website/public/images/releases/{MINOR_VERSION}/-```--## Tips--- **Start early**: Begin documenting features as they're developed-- **User perspective**: Write for users, not developers-- **Be concise**: 1-2 sentences per feature-- **Visual first**: Illustrations should showcase the feature clearly-- **Consistent style**: Match tone and structure of previous changelogs-- **Test links**: Verify all image paths work before committing-- **Research thoroughly**: Use codebase search to understand features deeplydiff --git a/.cursor/rules/code-style.mdc b/.cursor/rules/code-style.mdcdeleted file mode 100644index 77473f09a00..00000000000--- a/.cursor/rules/code-style.mdc+++ /dev/null@@ -1,204 +0,0 @@-----description: Code style guidelines for Twenty CRM-globs: []-alwaysApply: true-----# Code Style Guidelines--## Formatting Standards-- **Prettier**: 2-space indentation, single quotes, trailing commas, semicolons-- **Print width**: 80 characters-- **Oxlint**: No unused imports, consistent import ordering, prefer const over let--## Naming Conventions-```typescript-// ✅ Variables and functions - camelCase-const userAccountBalance = 1000;-const calculateMonthlyPayment = () => {};--// ✅ Constants - SCREAMING_SNAKE_CASE-const API_ENDPOINTS = {- USERS: '/api/users',- ORDERS: '/api/orders',-} as const;--// ✅ Types and Classes - PascalCase-class UserService {}-type UserAccountData = {};-type ButtonProps = {}; // Component props suffix with 'Props'--// ✅ Files and directories - kebab-case-// user-profile.component.tsx-// user-profile.styles.ts--// ❌ NEVER use abbreviations in variable names-// Bad-const users = data.map((u) => u.name);-const field = items.find((f) => f.id === id);--// Good-const users = data.map((user) => user.name);-const field = items.find((item) => item.id === id);-const fieldMetadata = inlineFields.find(- (fieldMetadataItem) => fieldMetadataItem.name === fieldName,-);-```--## Import Organization-```typescript-// ✅ Correct import order-// 1. External libraries-import React from 'react';-import { useCallback } from 'react';-import styled from 'styled-components';--// 2. Internal modules (absolute paths)-import { Button } from '@/components/ui';-import { UserService } from '@/services';--// 3. Relative imports-import { UserCardProps } from './types';-```--## Function Structure-```typescript-// ✅ Small, focused functions-// ✅ Required parameters first, optional last-const processUserData = (- user: User,- options: ProcessingOptions,- callback?: (result: ProcessedUser) => void-): ProcessedUser => {- const processedUser = transformUserData(user);- applyOptions(processedUser, options);-- if (callback) {- callback(processedUser);- }-- return processedUser;-};-```--## Collection Transformations-```typescript-// ✅ Prefer array transformations for simple mapping, filtering, and classification-const activeUsers = users.filter((user) => user.isActive === true);-const userNames = users.map((user) => user.name);--const { payingUsers, nonPayingUsers } = users.reduce<{- payingUsers: User[];- nonPayingUsers: User[];-}>(- (accumulator, user) => {- if (user.isPaying === true) {- accumulator.payingUsers.push(user);- } else {- accumulator.nonPayingUsers.push(user);- }-- return accumulator;- },- { payingUsers: [], nonPayingUsers: [] },-);--// ❌ Avoid manual loops when map, filter, or reduce keeps the code clear-const payingUsers: User[] = [];--for (const user of users) {- if (user.isPaying === true) {- payingUsers.push(user);- }-}-```--## Comments-```typescript-// ✅ Use short-form comments, NOT JSDoc blocks-// ✅ Explain business logic and non-obvious intentions (WHY, not WHAT)-// Apply 15% discount for premium users with orders > $100-const discount = isPremiumUser && orderTotal > 100 ? 0.15 : 0;--// TODO: Replace with proper authentication service-const isAuthenticated = localStorage.getItem('token') !== null;--// ✅ Multi-line comments use multiple // lines (NOT /** */ blocks)-// Calculates the total price after applying tax and discount-// Returns the final price that should be charged to the customer-const calculateTotalPrice = (basePrice: number): number => {- // Implementation-};--// ❌ AVOID obvious comments that just describe what code does-// Bad: Get all inline fields dynamically-const { inlineFieldMetadataItems } = useFieldListFieldMetadataItems({...});--// Bad: Define standard fields in display order-const standardFieldOrder = ['startsAt', 'endsAt', 'conferenceLink'];--// Bad: Split fields into standard and custom-const standardFields = standardFieldOrder.map(...)--// ✅ GOOD: Only comment if explaining non-obvious business logic-// Calendar events display standard fields first, then custom fields after participants-// to maintain consistency with the legacy UI behavior-const standardFields = standardFieldOrder.map(...)--// ❌ AVOID JSDoc blocks - use short comments instead-/**- * This style is NOT preferred in this codebase- */-```--**Comment Guidelines:**-- **DO** comment complex business rules or domain-specific logic-- **DO** comment non-obvious algorithmic decisions-- **DO** add TODOs for future improvements-- **DON'T** comment obvious variable declarations or function calls-- **DON'T** comment what is already clear from well-named variables/functions-- **DON'T** add comments that just repeat what the code says--## Utility Helpers-```typescript-// ✅ Use existing utility helpers instead of manual checks-import { isDefined } from 'twenty-shared/utils';-import { isNonEmptyString, isNonEmptyArray } from '@sniptt/guards';--// ❌ Manual type guards-const validItems = items.filter((item): item is Item => item !== undefined);-const hasValue = value !== null && value !== undefined;--// ✅ Use utility helpers-const validItems = items.filter(isDefined);-const hasValue = isDefined(value);--// Other useful helpers:-// - isDefined(value) - checks !== null && !== undefined-// - isNonEmptyString(value) - checks string is defined and not empty-// - isNonEmptyArray(value) - checks array is defined and has items-```--## Security Patterns-```typescript-// ✅ CSV Export: Always apply security first, then formatting-const safeValue = formatValueForCSV(sanitizeValueForCSVExport(userInput));--// ✅ Input validation before processing-const sanitizedInput = validateAndSanitize(userInput);-const result = processData(sanitizedInput);-```--## Error Handling-```typescript-// ✅ Proper error types and meaningful messages-try {- const user = await userService.findById(userId);- if (!user) {- throw new UserNotFoundError(`User with ID ${userId} not found`);- }- return user;-} catch (error) {- logger.error('Failed to fetch user', { userId, error });- throw error;-}-```diff --git a/.cursor/rules/creating-syncable-entity.mdc b/.cursor/rules/creating-syncable-entity.mdcdeleted file mode 100644index 4661a443738..00000000000--- a/.cursor/rules/creating-syncable-entity.mdc+++ /dev/null@@ -1,219 +0,0 @@-----description: Main guide for creating syncable entities in Twenty's workspace migration system-globs: ["**/metadata-modules/**", "**/workspace-migration/**"]-alwaysApply: false------# Creating a New Syncable Entity - Main Guide--This is the main guide for creating **syncable entities** in Twenty's workspace migration architecture.--## Documentation Structure--This main guide provides a high-level overview and navigation hub.--**⚡ Skills** (`.cursor/skills/syncable-entity-*/SKILL.md`) - Concise, action-oriented implementation guides for each step. Reference these when creating a new syncable entity.--**When to use:**-- Start here for architecture overview and workflow-- Reference specific skills (`@syncable-entity-types-and-constants`) when implementing each step--## What is a Syncable Entity?--A syncable entity is a metadata entity that:-- Has a **`universalIdentifier`**: A unique identifier used for syncing entities across workspaces/applications-- Has an **`applicationId`**: Links the entity to an application (Standard or Custom applications)-- Participates in the **workspace migration system**: Can be created, updated, and deleted through the migration pipeline-- Is **cached as a flat entity**: Denormalized representation for efficient validation and change detection--Examples: `skill`, `agent`, `view`, `viewField`, `role`, `pageLayout`, etc.--## Architecture Overview--```-Input DTO → Transform → Universal Flat Entity → Builder/Validator → Runner → Database- ↓- Cache Service-```--**Key Components:**-- **TypeORM Entity**: Database model extending `SyncableEntity`-- **Flat Entity**: Denormalized type (no relations, dates as strings) - for caching-- **Universal Flat Entity**: Flat entity with foreign keys mapped to universal identifiers - for migrations-- **Transform Utils**: Convert DTOs to universal flat entities-- **Builder/Validator**: Validate and create migration actions-- **Runner**: Execute actions against the database--## Implementation Steps--Follow these skills in order:--### 1️⃣ **Foundation: Types & Constants** → `@syncable-entity-types-and-constants`--**What:** Define all types, entities, and register in central constants--**Tasks:**-- Create TypeORM entity (extends `SyncableEntity`)-- Define flat entity types-- Define action types (universal + flat)-- Register in 5 central constants--**Why first:** Everything else depends on these types-------### 2️⃣ **Data Layer: Cache & Transform** → `@syncable-entity-cache-and-transform`--**What:** Handle conversion between different representations--**Tasks:**-- Create cache service-- Create entity-to-flat conversion-- Create input transform utils-- Handle foreign key resolution--**Dependencies:** Requires Step 1-------### 3️⃣ **Business Logic: Builder & Validation** → `@syncable-entity-builder-and-validation`--**What:** Validate business rules and create actions--**Tasks:**-- Create validator service (never throws, never mutates)-- Create builder service-- Wire into orchestrator (⚠️ critical!)--**Dependencies:** Requires Steps 1-2-------### 4️⃣ **Execution: Runner & Actions** → `@syncable-entity-runner-and-actions`--**What:** Execute migration actions against the database--**Tasks:**-- Create action handlers (create/update/delete)-- Implement transpilation methods-- Create universal-to-flat conversion utilities--**Dependencies:** Requires Steps 1-3-------### 5️⃣ **Assembly: Integration** → `@syncable-entity-integration`--**What:** Wire everything together--**Tasks:**-- Register in 3 NestJS modules-- Create service and resolver layers-- Use exception interceptor--**Dependencies:** Requires Steps 1-4-------### 6️⃣ **Testing: Integration Tests** (**MANDATORY**) → `@syncable-entity-testing`--**What:** Comprehensive test suite--**Tasks:**-- Create test utilities-- Write failing tests (all validator exceptions)-- Write successful tests (all CRUD operations)-- Use snapshot testing--**Dependencies:** Requires all previous steps-------## Quick Reference--### Multi-Agent Workflow--For parallel development:-1. **Agent 1** (Foundation): Complete Step 1 first - unblocks everyone-2. **Agent 2** (Cache): Can start immediately after Step 1-3. **Agent 3** (Builder): Can work in parallel with Agent 4 after Step 1-4. **Agent 4** (Runner): Can work in parallel with Agent 3 after Step 1-5. **Agent 5** (Integration): Assembles everything after Steps 2-4--### Key Design Principles--| Layer | Responsibility | Can Throw? | Can Mutate? |-|-------|---------------|------------|-------------|-| Transform Utils | Data transformation | Yes (input validation) | N/A (creates new) |-| Validator | Business rule validation | **No** (returns errors) | **No** |-| Builder | Action creation | **No** (returns errors) | **No** |-| Runner | Database operations | Yes (DB errors) | Yes (via TypeORM) |--### Common Pitfalls--⚠️ **Most Commonly Forgotten:**-1. Wiring builder in orchestrator service-2. Registering in all 3 modules (builder, validators, action handlers)-3. Setting `universalIdentifier` correctly in entity-to-flat conversion--⚠️ **Common Mistakes:**-1. Using regular IDs instead of universal identifiers in transform utils-2. Throwing exceptions in validators/builders-3. Mutating entity maps in validators/builders-4. Forgetting to handle JSONB properties with `SerializedRelation`--### File Locations--```-packages/twenty-shared/src/metadata/-└── all-metadata-name.constant.ts--packages/twenty-server/src/engine/metadata-modules/-├── my-entity/ # Step 1-│ └── entities/-├── flat-my-entity/ # Steps 1-2-│ ├── types/-│ ├── constants/-│ ├── services/-│ └── utils/-└── flat-entity/constant/ # Step 1 (central registries)- ├── all-entity-properties-configuration-by-metadata-name.constant.ts- ├── all-one-to-many-metadata-relations.constant.ts- ├── all-many-to-one-metadata-foreign-key.constant.ts- └── all-many-to-one-metadata-relations.constant.ts--packages/twenty-server/src/engine/workspace-manager/workspace-migration/-├── workspace-migration-builder/ # Step 3-│ ├── builders/my-entity/-│ └── validators/services/-└── workspace-migration-runner/ # Step 4- └── action-handlers/my-entity/-```--### Complete Checklist--Before considering complete:-- [ ] All 6 guides completed-- [ ] TypeORM entity extends `SyncableEntity`-- [ ] All constants registered (5 central registries)-- [ ] Cache service with correct decorator-- [ ] Transform utils return universal flat entities-- [ ] Validator never throws/mutates-- [ ] Builder wired in orchestrator (⚠️ critical!)-- [ ] All 3 action handlers implemented-- [ ] All 3 modules updated-- [ ] **Integration tests written (MANDATORY)**-- [ ] **All failing scenarios covered**-- [ ] **All successful use cases tested**-------## Need Help?--Reference the appropriate skill for step-by-step guidance:-- `@syncable-entity-types-and-constants` - Types, entities, constants-- `@syncable-entity-cache-and-transform` - Cache & transform-- `@syncable-entity-builder-and-validation` - Builder & validation-- `@syncable-entity-runner-and-actions` - Runner & actions-- `@syncable-entity-integration` - Integration & wiring-- `@syncable-entity-testing` - Testing patternsdiff --git a/.cursor/rules/feedback-incorporation.mdc b/.cursor/rules/feedback-incorporation.mdcdeleted file mode 100644index 2fd0b44baaf..00000000000--- a/.cursor/rules/feedback-incorporation.mdc+++ /dev/null@@ -1,100 +0,0 @@-----description: Guidelines for incorporating user feedback and improving cursor rules-globs: []-alwaysApply: true-----# Feedback Incorporation Guidelines--## Post-Interaction Reflection--After each coding session or significant interaction, the AI should:--### 1. Reflect on User Feedback-- **Identify patterns** in user corrections or suggestions-- **Note recurring issues** that could be prevented with better rules-- **Recognize gaps** in current cursor rules or guidelines--### 2. Suggest Rule Improvements-When user provides feedback that reveals a pattern or preference:--```typescript-// Example feedback patterns to watch for:-// - "We don't use useEffect, handle state changes in event callbacks"-// - "We don't use JSDoc blocks, prefer // comments"-// - "Always use named exports, never default exports"-// - "We prefer functional components over class components"-// - "Use event handlers over useEffect for state updates"-```--### 3. Proactive Rule Suggestions-At the end of interactions, suggest:--```markdown-## 💡 Suggested Cursor Rule Updates--Based on your feedback today, I recommend adding/updating these rules:--**Code Style Rule Update:**-- Add preference for // comments over JSDoc blocks-- Enforce named exports only (no default exports)--**React Guidelines Update:**-- Document preference for event handlers over useEffect-- Add functional components only rule--Would you like me to help incorporate these into your cursor rules?-```--## Implementation Process--### When to Suggest Updates-- User corrects the same type of mistake multiple times-- User explains a codebase-specific preference-- User points out missing functionality or incomplete implementations-- User provides context about existing patterns not captured in rules--### How to Present Suggestions-1. **Summarize the pattern** observed from feedback-2. **Propose specific rule language** that would prevent the issue-3. **Explain the benefit** of codifying this knowledge-4. **Ask for confirmation** before implementing--### Rule Categories to Consider-- **Code Style**: Formatting, naming, comment styles, export patterns-- **React Patterns**: Hook usage, component structure, state management-- **Architecture**: File organization, import patterns, component composition-- **Testing**: Test structure, naming, coverage expectations-- **Performance**: Optimization patterns, anti-patterns to avoid--## Example Feedback Integration--```markdown-## Today's Learning: React State Management Patterns--**User Feedback Received:**-- "We don't use useEffect, handle state changes in event callbacks"-- "We don't use JSDoc blocks, prefer // comments"-- "Always use named exports, never default exports"--**Proposed Rule Additions:**-```typescript-// ✅ React State Updates - Use event handlers, not useEffect-const handleButtonClick = () => {- setData(newData); // Direct state update in event handler-};--// ❌ Avoid useEffect for state updates-// useEffect(() => { setData(newData); }, [trigger]);--// ✅ Named exports only-export const UserComponent = () => {};-export const useUserData = () => {};-```--**Benefits:**-- Prevents useEffect overuse and related bugs-- Ensures consistent export patterns across codebase-- Documents preferred React patterns for the team-```--This approach helps the AI learn from each interaction and continuously improve the development experience.\ No newline at end of filediff --git a/.cursor/rules/file-structure.mdc b/.cursor/rules/file-structure.mdcdeleted file mode 100644index 5fdcb6d5463..00000000000--- a/.cursor/rules/file-structure.mdc+++ /dev/null@@ -1,107 +0,0 @@-----description: File structure guidelines for Twenty CRM-globs: []-alwaysApply: true-----# File Structure Guidelines--## Directory Organization-```-packages/twenty-front/src/-├── components/ # Reusable UI components-├── pages/ # Route components-├── modules/ # Feature modules-├── hooks/ # Custom hooks-├── services/ # API services-└── types/ # Type definitions--packages/twenty-server/src/-├── modules/ # Feature modules-├── entities/ # Database entities-├── dto/ # Data transfer objects-└── utils/ # Helper functions-```--## File Naming-- **kebab-case** for all files and directories-- **Descriptive suffixes** for clarity-```-// ✅ Correct naming-user-profile.component.tsx-user-profile.styles.ts-user-profile.test.tsx-user.service.ts-user.entity.ts-create-user.dto.ts-```--## Index Files & Barrel Exports-```typescript-// ✅ Clean barrel exports in index.ts-export { UserCard } from './user-card.component';-export { UserList } from './user-list.component';-export type { UserCardProps, UserListProps } from './types';--// ✅ Usage - clean imports-import { UserCard, UserList } from '@/components/user';-```--## Module Structure-```-src/modules/user/-├── components/ # Module-specific components-├── hooks/ # Module hooks-├── services/ # API services-├── types/ # Type definitions-└── index.ts # Module exports-```--## Import/Export Patterns-```typescript-// ✅ Import organization-// 1. External libraries-import React from 'react';-import styled from 'styled-components';--// 2. Internal modules (absolute paths)-import { Button } from '@/components/ui';-import { UserService } from '@/services';--// 3. Relative imports-import { UserCardProps } from './types';--// ✅ Named exports only (no default exports)-export const UserComponent = ({ user }: UserProps) => {- // Component implementation-};-```--## File Size Guidelines-- **Components**: Under 300 lines-- **Services**: Under 500 lines-- **Extract logic** into hooks/utilities when files grow large-- **Use composition** over large monolithic components--## Configuration Files--### Project Configuration-```-.vscode/ # VSCode settings-├── settings.json-├── extensions.json-└── launch.json--.github/ # GitHub workflows-├── workflows/-└── templates/--.cursor/ # Cursor rules-├── rules/-└── environment.json-```--### Build Configuration-- Keep build configs in root or package directories-- Use consistent naming for config files-- Comment complex configurations-- Version control all configuration filesdiff --git a/.cursor/rules/github-actions-security.mdc b/.cursor/rules/github-actions-security.mdcdeleted file mode 100644index f289026be94..00000000000--- a/.cursor/rules/github-actions-security.mdc+++ /dev/null@@ -1,72 +0,0 @@-----description: GitHub Actions security guidelines for supply chain protection-globs: **/.github/**/*.yml, **/.github/**/*.yaml-alwaysApply: false------# GitHub Actions Security--## Pin Third-Party Actions to Commit SHAs--Always reference external actions and reusable workflows by their full commit SHA, never by a mutable tag or branch. Tags can be force-pushed by a compromised maintainer account.--```yaml-# ❌ Mutable tag — vulnerable to supply chain attacks-uses: actions/checkout@v4-uses: actions/setup-node@v4--# ✅ Pinned to commit SHA with tag comment for readability-uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1-uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0-```--## Prefer `gh api` Over Third-Party Dispatch Actions--For repository dispatch calls, use `gh api` directly instead of third-party actions like `peter-evans/repository-dispatch`. This eliminates a supply-chain dependency entirely.--```yaml-# ✅ Use env vars + bracket notation to prevent injection-- name: Dispatch to target repo- env:- GH_TOKEN: ${{ secrets.DISPATCH_TOKEN }}- PR_NUMBER: ${{ github.event.pull_request.number }}- BRANCH: ${{ github.event.workflow_run.head_branch }}- run: |- gh api repos/org/repo/dispatches \- -f event_type=my-event \- -f "client_payload[pr_number]=$PR_NUMBER" \- -f "client_payload[branch]=$BRANCH"--# ✅ Simple dispatch without payload-- name: Trigger workflow- env:- GH_TOKEN: ${{ secrets.DISPATCH_TOKEN }}- run: |- gh api repos/org/repo/dispatches -f event_type=my-event--# ❌ Third-party action dependency-- uses: peter-evans/repository-dispatch@v2- with:- token: ${{ secrets.DISPATCH_TOKEN }}- repository: org/repo- event-type: my-event--# ❌ Inline ${{ }} in shell — vulnerable to injection-- run: |- gh api repos/org/repo/dispatches --input - <<EOF- {"event_type": "x", "client_payload": {"branch": "${{ github.head_ref }}"}}- EOF-```--## Minimal Permissions--Always declare explicit `permissions` at the job level with the least privilege required. Never rely on the default `GITHUB_TOKEN` permissions.--```yaml-# ✅ Explicit minimal permissions-permissions:- contents: read--# ❌ Overly broad or implicit permissions-permissions: write-all-```diff --git a/.cursor/rules/nx-rules.mdc b/.cursor/rules/nx-rules.mdcdeleted file mode 100644index 3c5851b8966..00000000000--- a/.cursor/rules/nx-rules.mdc+++ /dev/null@@ -1,89 +0,0 @@-----description: Guidelines and best practices for working with Nx in the Twenty workspace, including workspace architecture understanding, configuration management, and generator usage.-globs: ["**/nx.json", "**/project.json", "**/workspace.json"]-alwaysApply: true------# Nx Guidelines--## Core Commands-```bash-# Run target for specific project-npx nx run twenty-front:build-npx nx run twenty-server:test--# Lint diff with main (recommended - much faster!)-npx nx lint:diff-with-main twenty-front # Lint only files changed vs main-npx nx lint:diff-with-main twenty-server-npx nx lint:diff-with-main twenty-front --configuration=fix # Auto-fix changed files--# Run target for all projects (slower)-npx nx run-many --target=build --all-npx nx run-many --target=test --projects=twenty-front,twenty-server--# Generate/modify projects-npx nx g @nx/react:app my-app-npx nx g @nx/react:component my-component-```--## Project Structure-- Each package has a `project.json` with targets-- Dependencies managed through `tsconfig.json` path mappings-- Shared libraries in `packages/` directory--## Build Targets-```json-// project.json-{- "targets": {- "build": {- "executor": "@nx/vite:build",- "options": { "outputPath": "dist/packages/twenty-front" }- },- "test": {- "executor": "@nx/jest:jest",- "options": { "jestConfig": "packages/twenty-front/jest.config.mjs" }- }- }-}-```--## Linting Strategy-For faster development, always prefer linting only changed files:-- Use `npx nx lint:diff-with-main <project>` to lint only files changed vs main branch-- Use `--configuration=fix` to auto-fix issues in changed files-- Only use `npx nx lint <project>` when you need to lint the entire project--## Dependency Graph-```bash-# View project dependencies-npx nx graph--# Check what's affected by changes (runs target on affected projects)-npx nx affected --target=test-npx nx affected --target=build --base=main-```--## Library Management-- Use `npx nx g @nx/workspace:library` generator for shared libs-- Internal imports use `@/` path mapping-- Libraries must export through index.ts barrel files--## Cache Configuration-- Nx caches build outputs and test results-- Configure `outputs` in project.json targets-- Use `inputs` to define what invalidates cache--```json-{- "build": {- "outputs": ["dist/packages/my-app"],- "inputs": ["source", "^source"],- "cache": true- }-}-```----diff --git a/.cursor/rules/react-general-guidelines.mdc b/.cursor/rules/react-general-guidelines.mdcdeleted file mode 100644index 42e70328842..00000000000--- a/.cursor/rules/react-general-guidelines.mdc+++ /dev/null@@ -1,85 +0,0 @@-----description: React general guidelines for Twenty CRM-alwaysApply: false-----# React Guidelines--## Core Rules-- **Functional components only** (no classes)-- **Named exports only** (no default exports)-- **Event handlers over useEffect** for state updates--## Component Structure-```typescript-// ✅ Correct-export const UserProfile = ({ user, onEdit }: UserProfileProps) => {- const handleEdit = () => onEdit(user.id);-- return (- <StyledContainer>- <h1>{user.name}</h1>- <Button onClick={handleEdit}>Edit</Button>- </StyledContainer>- );-};-```--## Props & Event Handlers-```typescript-// ✅ Correct - Destructure props-const Button = ({ onClick, isDisabled, children }: ButtonProps) => (- <button onClick={onClick} disabled={isDisabled}>- {children}- </button>-);--// ✅ Correct - Event handlers over useEffect-const UserForm = ({ onSubmit }: UserFormProps) => {- const handleSubmit = async (data: FormData) => {- await onSubmit(data);- // Direct event handling, not useEffect- };-- return <Form onSubmit={handleSubmit} />;-};-```--## Component Design-- **Small, focused components** - Single responsibility-- **Composition over inheritance** - Combine simple components-- **Extract complex logic** into custom hooks--```typescript-// ✅ Good - Composed from smaller components-const UserCard = ({ user }: UserCardProps) => (- <StyledCard>- <UserAvatar user={user} />- <UserInfo user={user} />- <UserActions user={user} />- </StyledCard>-);-```--## Performance-```typescript-// ✅ Use memo for expensive components only-const ExpensiveChart = memo(({ data }: ChartProps) => {- // Complex rendering logic- return <ComplexChart data={data} />;-});--// ✅ Memoize callbacks when needed-const UserList = ({ users, onUserSelect }: UserListProps) => {- const handleUserSelect = useCallback((user: User) => {- onUserSelect(user);- }, [onUserSelect]);-- return (- <div>- {users.map(user => (- <UserItem key={user.id} user={user} onSelect={handleUserSelect} />- ))}- </div>- );-};-```diff --git a/.cursor/rules/react-state-management.mdc b/.cursor/rules/react-state-management.mdcdeleted file mode 100644index 9d6c53c87d3..00000000000--- a/.cursor/rules/react-state-management.mdc+++ /dev/null@@ -1,101 +0,0 @@-----description: React state management guidelines for Twenty CRM-alwaysApply: false-----# React State Management--## Jotai Patterns-```typescript-// ✅ Atoms for primitive state (use createAtomState for keyed state with optional persistence)-import { createAtomState } from '@/ui/utilities/state/jotai/utils/createAtomState';--export const currentUserState = createAtomState<User | null>({- key: 'currentUserState',- defaultValue: null,-});--// ✅ Derived atoms for computed state (use createAtomSelector)-import { createAtomSelector } from '@/ui/utilities/state/jotai/utils/createAtomSelector';--export const userDisplayNameSelector = createAtomSelector({- key: 'userDisplayNameSelector',- get: ({ get }) => {- const user = get(currentUserState);- return user ? `${user.firstName} ${user.lastName}` : 'Guest';- },-});--// ✅ Atom factory pattern for dynamic atoms (use createAtomFamilyState)-import { createAtomFamilyState } from '@/ui/utilities/state/jotai/utils/createAtomFamilyState';--export const userByIdState = createAtomFamilyState<User | null, string>({- key: 'userByIdState',- defaultValue: null,-});-```--## Jotai Hooks-```typescript-// useAtomState - read and write-import { useAtomState } from '@/ui/utilities/state/jotai/hooks/useAtomState';--// useAtomStateValue - read only-import { useAtomStateValue } from '@/ui/utilities/state/jotai/hooks/useAtomStateValue';--// useSetAtomState - write only-import { useSetAtomState } from '@/ui/utilities/state/jotai/hooks/useSetAtomState';-```--## Provider-Jotai works without a Provider by default. For scoped stores or testing, use `Provider` from `jotai`.--## Local State Guidelines-```typescript-// ✅ Multiple useState for unrelated state-const [isLoading, setIsLoading] = useState(false);-const [error, setError] = useState<string | null>(null);-const [data, setData] = useState<User[]>([]);--// ✅ useReducer for complex state logic-type FormAction =- | { type: 'SET_FIELD'; field: string; value: string }- | { type: 'SET_ERRORS'; errors: Record<string, string> }- | { type: 'RESET' };--const formReducer = (state: FormState, action: FormAction): FormState => {- switch (action.type) {- case 'SET_FIELD':- return { ...state, [action.field]: action.value };- case 'SET_ERRORS':- return { ...state, errors: action.errors };- case 'RESET':- return initialFormState;- default:- return state;- }-};-```--## Data Flow Rules-- **Props down, events up** - Unidirectional data flow-- **Avoid bidirectional binding** - Use callback functions-- **Normalize complex data** - Use lookup tables over nested objects--```typescript-// ✅ Normalized state structure-type UsersState = {- byId: Record<string, User>;- allIds: string[];-};--// ✅ Functional state updates-const increment = useCallback(() => {- setCount(prev => prev + 1);-}, []);-```--## Performance Tips-- Use atom factory pattern (createAtomFamilyState) for dynamic data collections-- Derived atoms (createAtomSelector) are automatically memoized by Jotai-- Avoid heavy computations in derived atoms-- Batch state updates when possiblediff --git a/.cursor/rules/sdk-esm-dependencies.mdc b/.cursor/rules/sdk-esm-dependencies.mdcdeleted file mode 100644index d16e9e06ba3..00000000000--- a/.cursor/rules/sdk-esm-dependencies.mdc+++ /dev/null@@ -1,53 +0,0 @@-----description: ESM dependency guidelines for twenty-sdk and create-twenty-app packages-globs: ["packages/twenty-sdk/**", "packages/create-twenty-app/**"]-alwaysApply: false------# ESM Dependency Guidelines--## Context--`twenty-sdk` and `create-twenty-app` are published as dual-format npm packages (ESM `.mjs` + CJS `.cjs`). Dependencies listed in `dependencies` are **externalized** by the Vite/Rollup build — they are not bundled, and consumers resolve them from `node_modules` at runtime.--This means **CJS-only dependencies break the ESM output**. When Rollup emits `import { foo } from 'cjs-package'`, Node.js ESM cannot resolve named exports from CommonJS modules, causing `SyntaxError: Named export 'foo' not found`.--## Rules--### Only add ESM-compatible dependencies--Before adding a new dependency to `package.json`, verify it supports ESM:-- Check for `"type": "module"` in its `package.json`-- Or check for an `"exports"` map with ESM entries-- Or check for a `"module"` field pointing to an ESM build--### Use native `node:fs/promises` for standard fs operations--```typescript-// ✅ Import native fs functions directly-import { readFile, writeFile, mkdir, rm, cp } from 'node:fs/promises';-import { createWriteStream, existsSync } from 'node:fs';--// ✅ Import only custom helpers from fs-utils (no native re-exports)-import { pathExists, ensureDir, emptyDir, copy, move, remove, readJson, writeJson, ensureFile } from '@/cli/utilities/file/fs-utils';--// ❌ Don't use fs-extra (CJS-only, breaks ESM bundle)-import * as fs from 'fs-extra';--// ❌ Don't use import * as fs from fs-utils (it doesn't re-export native fs)-import * as fs from '@/cli/utilities/file/fs-utils';-```--### Use `@/cli/utilities/string/kebab-case` instead of lodash--```typescript-// ✅ Use internal utility-import { kebabCase } from '@/cli/utilities/string/kebab-case';--// ❌ Don't use lodash single-function packages (CJS-only, unmaintained)-import kebabCase from 'lodash.kebabcase';-```--### When no ESM alternative exists--If a CJS-only package has no ESM replacement (e.g. `archiver`), add it to the `cjsOnlyPackages` list in `vite.config.node.ts` so it gets inlined into the bundle instead of externalized.diff --git a/.cursor/rules/server-migrations.mdc b/.cursor/rules/server-migrations.mdcdeleted file mode 100644index 44d93138e1b..00000000000--- a/.cursor/rules/server-migrations.mdc+++ /dev/null@@ -1,48 +0,0 @@-----description: Guidelines for generating and managing upgrade commands (instance commands and workspace commands) in twenty-server-globs: [- "packages/twenty-server/src/**/*.entity.ts",- "packages/twenty-server/src/database/commands/upgrade-version-command/**/*.ts"-]-alwaysApply: false------## Upgrade Commands (twenty-server)--The upgrade system uses two types of commands instead of raw TypeORM migrations:-- **Instance commands** — schema and data migrations that run once at the instance level.-- **Workspace commands** — commands that iterate over all active/suspended workspaces.--See `packages/twenty-server/docs/UPGRADE_COMMANDS.md` for full documentation.--### Instance Commands--- **When changing a `*.entity.ts` file**, generate an instance command:-- ```bash- npx nx run twenty-server:database:migrate:generate --name <name> --type <fast|slow>- ```--- **Fast commands** (`--type fast`, default) are for schema-only changes that must run immediately. They implement `FastInstanceCommand` with `up`/`down` methods and use the `@RegisteredInstanceCommand` decorator.--- **Slow commands** (`--type slow`) add a `runDataMigration` method for potentially long-running data backfills that execute before `up`. They only run when `--include-slow` is passed. Use the decorator with `{ type: 'slow' }`.--- The generator auto-registers the command in `instance-commands.constant.ts` — do not edit that file manually.--- **Keep commands consistent and reversible**: include both `up` and `down` logic. Do not delete or rewrite existing, committed commands unless on a pre-release branch.--- **Shipping a command for a future version (deferred drops)**: pass `--version <next-version>` (a `TWENTY_NEXT_VERSIONS` value) to the generator to write a command that registers but stays dormant until `nx version:bump` makes that version current — e.g. dropping a column one release after its replacement ships. Caveat: `@WasRemovedInUpgrade`/`@WasIntroducedInUpgrade` reject a still-dormant next-version command at boot (`unknown-step-name`), so keep the entity's `WasRemovedInUpgrade<T>` type wrapper and add the decorator only once the version is current. See `docs/UPGRADE_COMMANDS.md`.--### Workspace Commands--- Use the `@RegisteredWorkspaceCommand` decorator alongside nest-commander's `@Command` decorator.-- Extend `ActiveOrSuspendedWorkspaceCommandRunner` and implement `runOnWorkspace`.-- The base class provides `--dry-run`, `--verbose`, and workspace filter options automatically.--### Execution Order--Within a given version, commands run in this order (timestamp-sorted within each group):-1. Instance fast commands-2. Instance slow commands (only with `--include-slow`)-3. Workspace commands-diff --git a/.cursor/rules/testing-guidelines.mdc b/.cursor/rules/testing-guidelines.mdcdeleted file mode 100644index a2678a11460..00000000000--- a/.cursor/rules/testing-guidelines.mdc+++ /dev/null@@ -1,127 +0,0 @@-----description: Testing guidelines for Twenty CRM-alwaysApply: false-----# Testing Guidelines--## Test Structure (AAA Pattern)-```typescript-describe('UserService', () => {- describe('when getting user by ID', () => {- it('should return user data for valid ID', async () => {- // Arrange- const userId = '123';- const expectedUser = { id: '123', name: 'John' };- mockUserRepository.findById.mockResolvedValue(expectedUser);-- // Act- const result = await userService.getUserById(userId);-- // Assert- expect(result).toEqual(expectedUser);- });- });-});-```--## React Component Testing-```typescript-// ✅ Test user behavior, not implementation-describe('LoginForm', () => {- it('should display error message for invalid credentials', async () => {- const mockOnSubmit = jest.fn().mockRejectedValue(new Error('Invalid credentials'));- render(<LoginForm onSubmit={mockOnSubmit} />);-- await user.type(screen.getByLabelText(/email/i), '[email protected]');- await user.type(screen.getByLabelText(/password/i), 'wrongpassword');- await user.click(screen.getByRole('button', { name: /sign in/i }));-- expect(await screen.findByText(/invalid credentials/i)).toBeInTheDocument();- });-});-```--## Mocking Patterns-```typescript-// ✅ Service mocking-const mockEmailService = {- sendEmail: jest.fn().mockResolvedValue({ success: true }),- validateEmail: jest.fn().mockReturnValue(true),-};--// ✅ Test data factories-const createTestUser = (overrides = {}) => ({- id: uuid(),- email: '[email protected]',- name: 'Test User',- ...overrides,-});--beforeEach(() => {- jest.clearAllMocks();-});-```--## Testing Principles-- **Test behavior, not implementation** - Focus on what users see/do-- **Use descriptive test names** - "should [behavior] when [condition]"-- **Query by user-visible elements** - text, roles, labels over test IDs-- **Keep tests isolated** - Independent and repeatable-- **70% unit, 20% integration, 10% E2E** - Test pyramid--## Running Tests--### Single Test File Execution-```bash-# ✅ Run a specific test file (PREFERRED - Fast & Efficient)-npx jest path/to/test.test.ts --config=packages/PROJECT/jest.config.mjs--# Key Benefits:-# - Only runs the specific test file (fast)-# - No dependency resolution overhead-# - Immediate feedback for test development--# ✅ Examples:-# Frontend tests (use .test.ts extension)-npx jest packages/twenty-front/src/modules/localization/utils/detection/detectNumberFormat.test.ts --config=packages/twenty-front/jest.config.mjs--# Server tests (use .spec.ts extension)-npx jest packages/twenty-server/src/utils/__test__/is-work-email.spec.ts --config=packages/twenty-server/jest.config.mjs--# ❌ AVOID - This runs ALL tests (slow):-npx nx test twenty-front --testPathPattern=detectNumberFormat.test.ts--# ✅ Run tests in watch mode for development:-npx jest path/to/test.test.ts --config=packages/twenty-front/jest.config.mjs --watch--# ✅ Run with coverage for single file:-npx jest path/to/test.test.ts --config=packages/twenty-front/jest.config.mjs --coverage-```--### Test Suite Execution-```bash-# Run all tests for a project (use sparingly)-npx nx test twenty-front-npx nx test twenty-server--# Run tests matching a pattern-npx jest --testNamePattern="UserService" --config=packages/twenty-front/jest.config.mjs-```--## Common Patterns-```typescript-// Async testing-await waitFor(() => {- expect(screen.getByText('Loading...')).not.toBeInTheDocument();-});--// User interactions-await user.click(screen.getByRole('button'));-await user.type(screen.getByLabelText(/search/i), 'query');--// API integration tests-const response = await request(app)- .post('/api/users')- .send(userData)- .expect(201);-```diff --git a/.cursor/rules/translations.mdc b/.cursor/rules/translations.mdcdeleted file mode 100644index aaef178efb7..00000000000--- a/.cursor/rules/translations.mdc+++ /dev/null@@ -1,290 +0,0 @@-----description: Translation guidelines for Twenty CRM-alwaysApply: false-----# Translation Guidelines--## Internationalization (i18n) Overview--### Supported Languages-- English (en) - Primary language-- French (fr) - Secondary language-- German (de) - Planned-- Spanish (es) - Planned-- Additional languages based on community contributions--### i18n Architecture-- Use react-i18next for React components-- Store translations in JSON files-- Implement namespace-based organization-- Support for interpolation and pluralization--## File Structure--### Translation Files-```-src/locales/-├── en/ # English translations-│ ├── common.json # Common UI strings-│ ├── auth.json # Authentication strings-│ ├── dashboard.json # Dashboard specific-│ ├── forms.json # Form labels and validation-│ └── errors.json # Error messages-├── fr/ # French translations-│ ├── common.json-│ ├── auth.json-│ └── ...-└── index.ts # i18n configuration-```--### Translation Keys-- Use nested objects for organization-- Follow consistent naming patterns-- Include context in key names- ```json- {- "auth": {- "login": {- "title": "Sign In",- "email": "Email Address",- "password": "Password",- "submit": "Sign In",- "forgotPassword": "Forgot Password?"- },- "register": {- "title": "Create Account",- "confirmPassword": "Confirm Password"- }- }- }- ```--## Translation Implementation--### React Components-- Use useTranslation hook-- Specify namespaces for better organization-- Handle loading states properly- ```typescript- // ✅ Correct- import { useTranslation } from 'react-i18next';-- const LoginForm = () => {- const { t } = useTranslation('auth');-- return (- <form>- <h1>{t('login.title')}</h1>- <input- placeholder={t('login.email')}- type="email"- />- <input- placeholder={t('login.password')}- type="password"- />- <button type="submit">- {t('login.submit')}- </button>- </form>- );- };- ```--### Interpolation-- Use interpolation for dynamic content-- Pass variables through t() function-- Keep interpolation simple and readable- ```typescript- // ✅ Correct- const WelcomeMessage = ({ userName }: { userName: string }) => {- const { t } = useTranslation('common');-- return (- <h1>{t('welcome.message', { name: userName })}</h1>- );- };-- // Translation file- {- "welcome": {- "message": "Welcome back, {{name}}!"- }- }- ```--### Pluralization-- Handle singular/plural forms correctly-- Use count-based pluralization-- Support different plural rules per language- ```typescript- // ✅ Correct- const ItemCount = ({ count }: { count: number }) => {- const { t } = useTranslation('common');-- return (- <span>{t('items.count', { count })}</span>- );- };-- // Translation file- {- "items": {- "count_one": "{{count}} item",- "count_other": "{{count}} items"- }- }- ```--## Translation Management--### Adding New Strings-1. Add English translation first-2. Use descriptive keys that indicate context-3. Include comments for translators when needed-4. Test with long translations to ensure UI flexibility- ```json- {- "user": {- "profile": {- // Displayed in user profile header- "displayName": "Display Name",- // Used in forms when editing profile- "editDisplayName": "Edit Display Name",- // Confirmation message after profile update- "updateSuccess": "Profile updated successfully"- }- }- }- ```--### Translation Validation-- Use TypeScript for translation key validation-- Implement automated checks for missing translations-- Validate interpolation parameters- ```typescript- // ✅ Correct - Type-safe translations- type TranslationKey =- | 'auth.login.title'- | 'auth.login.email'- | 'auth.login.password'- | 'common.welcome.message';-- const t = (key: TranslationKey, options?: any) => {- // Translation implementation- };- ```--## Best Practices--### Key Naming-- Use descriptive, hierarchical keys-- Avoid abbreviations-- Group related translations-- Keep keys consistent across languages- ```json- // ✅ Correct- {- "dashboard": {- "header": {- "title": "Dashboard",- "subtitle": "Welcome to your workspace"- },- "actions": {- "createNew": "Create New",- "refresh": "Refresh Data",- "export": "Export"- }- }- }-- // ❌ Incorrect- {- "dash_title": "Dashboard",- "newBtn": "New",- "refreshData": "Refresh"- }- ```--### String Guidelines-- Write clear, concise text-- Use consistent terminology-- Consider character limits for UI elements-- Avoid concatenating translated strings- ```json- // ✅ Correct- {- "user": {- "status": {- "online": "Online",- "offline": "Offline",- "away": "Away"- }- }- }-- // ❌ Incorrect - Don't concatenate- {- "user": {- "statusPrefix": "User is ",- "statusOnline": "online"- }- }- ```--### Context Information-- Provide context for translators-- Include character limits when relevant-- Explain when/where text appears-- Note any technical constraints- ```json- {- "button": {- // Primary action button, max 20 characters- "save": "Save Changes",- // Secondary button in modal footer- "cancel": "Cancel",- // Destructive action, should sound cautious- "delete": "Delete Permanently"- }- }- ```--## Workflow--### Development Process-1. Develop features with English translations-2. Use placeholder keys during development-3. Finalize translation keys before feature completion-4. Add translations to all supported languages-5. Test with different language strings--### Translation Updates-1. Create translation tasks for new features-2. Provide context and screenshots to translators-3. Review translations for consistency-4. Test UI with translated strings-5. Update documentation when needed--### Quality Assurance-- Review translations in context-- Test with longest expected translations-- Verify formatting with interpolation-- Check for cultural appropriateness-- Ensure accessibility with screen readers--## Maintenance--### Regular Tasks-- Review and update outdated translations-- Check for unused translation keys-- Maintain consistency across languages-- Update translation documentation-- Monitor for missing translations in new features--### Tools and Automation-- Use automated translation validation-- Implement missing translation detection-- Set up continuous integration checks-- Maintain translation coverage reports-- Use translation management platforms when neededdiff --git a/.cursor/rules/typescript-guidelines.mdc b/.cursor/rules/typescript-guidelines.mdcdeleted file mode 100644index b5387243bf1..00000000000--- a/.cursor/rules/typescript-guidelines.mdc+++ /dev/null@@ -1,182 +0,0 @@-----description: TypeScript best practices and conventions for the Twenty codebase, including strict typing, naming conventions, and type safety guidelines.-alwaysApply: false---------description: TypeScript best practices and conventions for the Twenty codebase, including strict typing, naming conventions, and type safety guidelines.-globs: ["**/*.ts", "**/*.tsx"]-alwaysApply: false------# TypeScript Guidelines--## Core TypeScript Principles-Twenty enforces strict TypeScript usage to ensure type safety and maintainable code. This document outlines our TypeScript conventions and best practices.--## Type Safety--### Strict Typing-- **No 'any' type allowed**-- TypeScript strict mode enabled-- noImplicitAny enabled- ```typescript- // ✅ Correct- function processUser(user: User) {- return user.name;- }-- // ❌ Incorrect- function processUser(user: any) {- return user.name;- }- ```--### Type Definitions--#### Types over Interfaces-- Use `type` for all type definitions-- Exception: When extending third-party interfaces- ```typescript- // ✅ Correct- type User = {- id: string;- name: string;- email: string;- };-- // ❌ Incorrect- interface User {- id: string;- name: string;- email: string;- }- ```--### String Literals over Enums-- Use string literal unions instead of enums-- Exception: GraphQL enums- ```typescript- // ✅ Correct- type UserRole = 'admin' | 'user' | 'guest';-- // ❌ Incorrect- enum UserRole {- Admin = 'admin',- User = 'user',- Guest = 'guest',- }- ```--## Naming Conventions--### Component Props-- Suffix component prop types with 'Props'-- Keep props focused and single-purpose- ```typescript- // ✅ Correct- type ButtonProps = {- label: string;- onClick: () => void;- variant?: 'primary' | 'secondary';- };-- // ❌ Incorrect- type ButtonParameters = {- label: string;- onClick: () => void;- variant?: 'primary' | 'secondary';- };- ```--## Type Inference--### Leverage TypeScript Inference-- Use type inference when types are clear-- Explicitly type when inference is ambiguous- ```typescript- // ✅ Correct - Clear inference- const users = ['John', 'Jane']; // inferred as string[]-- // ✅ Correct - Explicit typing needed- const processUser = (user: User): UserResponse => {- // Complex processing- return response;- };-- // ❌ Incorrect - Unnecessary explicit typing- const users: string[] = ['John', 'Jane'];- ```--## Best Practices--### Type Guards-- Use type guards for runtime type checking-- Prefer discriminated unions- ```typescript- // ✅ Correct- type Success = {- type: 'success';- data: User;- };-- type Error = {- type: 'error';- message: string;- };-- type Result = Success | Error;-- function handleResult(result: Result) {- if (result.type === 'success') {- // TypeScript knows result.data exists- console.log(result.data);- }- }- ```--### Generics-- Use generics for reusable type patterns-- Keep generic names descriptive- ```typescript- // ✅ Correct- type ApiResponse<TData> = {- data: TData;- status: number;- message: string;- };-- // ❌ Incorrect- type ApiResponse<T> = {- data: T;- status: number;- message: string;- };- ```--### Type Exports-- Export types when they're used across files-- Keep type definitions close to their usage- ```typescript- // types.ts- export type User = {- id: string;- name: string;- };-- // UserComponent.tsx- import { type User } from './types';- ```--### Utility Types-- Leverage TypeScript utility types-- Create custom utility types for repeated patterns- ```typescript- // Built-in utility types- type UserPartial = Partial<User>;- type UserReadonly = Readonly<User>;-- // Custom utility types- type NonNullableProperties<T> = {- [P in keyof T]: NonNullable<T[P]>;- };- ```diff --git a/.cursor/worktrees.json b/.cursor/worktrees.jsondeleted file mode 100644index 2711ebb899a..00000000000--- a/.cursor/worktrees.json+++ /dev/null@@ -1,8 +0,0 @@-{- "setup-worktree": [- "nvm use",- "yarn",- "cp $ROOT_WORKTREE_PATH/packages/twenty-server/.env packages/twenty-server/.env || true",- "cp $ROOT_WORKTREE_PATH/packages/twenty-front/.env packages/twenty-front/.env || true"- ]-}diff --git a/.github/workflows/ci-agent-skills-drift.yaml b/.github/workflows/ci-agent-skills-drift.yamlnew file mode 100644index 00000000000..f2e16429029--- /dev/null+++ b/.github/workflows/ci-agent-skills-drift.yaml@@ -0,0 +1,199 @@+name: CI Agent Skills Drift++# When a PR changes the app-development surface (twenty-sdk, create-twenty-app,+# twenty-client-sdk, or the shared manifest types), an agent checks whether the+# canonical skill content under packages/twenty-agent-skills is impacted and,+# only when it is, posts a single sticky comment with its findings.+#+# This is the skills counterpart to ci-app-docs-drift.yaml: the same source+# changes that stale the docs also stale the guidance agents follow.++on:+ pull_request:++permissions:+ contents: read+ id-token: write++concurrency:+ group: ${{ github.workflow }}-${{ github.ref }}+ cancel-in-progress: true++jobs:+ changed-files-check:+ uses: ./.github/workflows/changed-files.yaml+ with:+ files: |+ packages/twenty-sdk/**+ packages/create-twenty-app/**+ packages/twenty-client-sdk/**+ packages/twenty-shared/src/application/**+ packages/twenty-shared/src/types/**++ agent-skills-drift-check:+ needs: changed-files-check+ # Secrets are unavailable on fork PRs; skip there and on bot PRs.+ if: >-+ needs.changed-files-check.outputs.any_changed == 'true' &&+ github.event.pull_request.head.repo.full_name == github.repository &&+ github.event.pull_request.user.type != 'Bot'+ timeout-minutes: 30+ runs-on: ubuntu-latest+ permissions:+ contents: read+ pull-requests: write+ id-token: write+ steps:+ - name: Checkout repository+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1+ with:+ fetch-depth: 0++ - name: Run agent skills drift agent+ id: drift-agent+ uses: anthropics/claude-code-action@ac7e24bf2938964b8ab203e417a2773802392ddd # v1.0.146+ with:+ claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}+ claude_args: |+ --max-turns 60 --json-schema '{"type":"object","properties":{"hasDrift":{"type":"boolean"},"summary":{"type":"string"}},"required":["hasDrift","summary"]}' --allowedTools "Bash(git diff *),Bash(git log *),Bash(git show *),Bash(grep *),Bash(cat *),Bash(ls *),Bash(find *),Bash(head *),Bash(tail *),Bash(gh pr comment *)"+ prompt: |+ You are the agent-skills drift checker for the twenty repository.++ A pull request changed files in the app-development platform. Your job is to+ decide whether the skill guidance under `packages/twenty-agent-skills/`+ is impacted, and report your findings as ONE pull request comment.++ These skills tell coding agents how to build Twenty apps. When they go stale+ an agent confidently runs a command that no longer exists, so wrong guidance+ is worse here than a missing doc page.++ ## Canonical source only++ `packages/twenty-agent-skills/skills/` and+ `packages/twenty-agent-skills/references/` are the canonical content.++ `packages/twenty-agent-skills/dist/` is generated for distribution and is+ not committed to main. Report the canonical file that needs an edit.++ ## Step 1 — Understand the change++ The PR branch is checked out with full history; the base branch is+ `origin/${{ github.base_ref }}`. Inspect what the PR changes however you+ see fit. Only these kinds of changes are skill-relevant:++ - CLI commands, subcommands, flags, defaults, or help text+ (`packages/twenty-sdk/src/cli/commands/**`)+ - `define*` function signatures, config properties, validation rules,+ or their warnings (`packages/twenty-sdk/src/sdk/define/**`)+ - Enum / string-union values and manifest types+ (`packages/twenty-shared/src/application/**`, `packages/twenty-shared/src/types/**`)+ - Exports added/removed/renamed in the `exports` maps of `twenty-sdk` or+ `twenty-client-sdk` package.json, or in their public entry points+ - Front-component runtime hooks and host API+ (`packages/twenty-sdk/src/sdk/front-component/**`)+ - The scaffold template (`packages/create-twenty-app/src/constants/template/**`)+ and scaffolder flags/prompts (`packages/create-twenty-app/src/cli.ts`,+ `create-app.command.ts`)+ - Environment variables injected into logic functions or front components+ - Error codes surfaced to app developers+ - Default ports and instance URLs used during development++ Internal refactors, tests, and implementation-only changes are NOT relevant —+ if the changes contain only those, say so and stop.++ ## Step 2 — Map to skill content++ Use this mapping to know which files to check (read the actual files, all+ paths relative to `packages/twenty-agent-skills/`):++ | Source area | Skill content |+ |---|---|+ | CLI commands (`src/cli/commands`) | `references/manage-app/cli-and-sync.md`, `skills/manage-app/SKILL.md`, `references/concepts/operating-rules.md` |+ | Scaffolder flags, prompts, template | `skills/create-app/SKILL.md`, `references/develop-app/app-structure.md` |+ | `defineObject`/`defineField`/relations/indexes | `references/develop-app/data-model.md` |+ | `defineApplication`/roles/install hooks/variables | `references/concepts/how-apps-work.md`, `references/publish-app/prepare-for-app-store.md` |+ | Logic functions, triggers, connections, agents/skills | `references/develop-app/logic.md` |+ | Workflows and their lifecycle | `references/develop-app/workflows.md` |+ | Views, navigation, page layouts, command menu | `references/develop-app/layout.md`, `references/develop-app/standalone-pages.md` |+ | Front components, SDK imports, runtime hooks | `references/develop-app/front-components.md`, `references/design/front-component-ui.md` |+ | Test layout, test target ports | `references/develop-app/tests.md`, `references/concepts/operating-rules.md` |+ | Publish/install/deploy, versioning | `references/publish-app/prepare-for-app-store.md`, `skills/publish-app/SKILL.md` |+ | MCP endpoints, transport, auth | `references/use-twenty-mcp/setup.md`, `references/use-twenty-mcp/result-formatting.md` |+ | Enum value sets (FieldType, ViewType, availabilityType, NavigationMenuItemType, ...) | the reference documenting that value set (search for the enum name) |++ Two extra checks specific to this package:++ - `scripts/validators/` encodes cross-document contracts as literal string+ fragments (exact commands, ports, section headings). A renamed command or+ changed port can make a validator assert something no longer true, so check+ whether the change invalidates a fragment there.+ - `references/concepts/operating-rules.md` is the single source of truth for+ the durable rules and names exact commands. A command rename lands here.++ Also check whether the PR already updates the impacted files — if it does,+ verify the update matches the code change.++ ## Step 3 — Report++ If there is NO skill impact, do NOT post or create any comment.+ Skip the comment entirely and go straight to Step 4.++ Only when the skills are impacted, post exactly one comment on PR+ #${{ github.event.pull_request.number }} with:+ `gh pr comment ${{ github.event.pull_request.number }} --edit-last --create-if-none --body ...`+ (this updates the previous drift-check comment in place on subsequent runs).+ Start the comment body with the marker `<!-- agent-skills-drift-check -->`.++ Comment format:+ - Title line: `### Agent skills drift check`+ - A table with columns **Change** (what changed in the code),+ **Skill file** (repo-relative path, canonical only), **Status**+ (`✅ already updated in this PR` / `⚠️ needs update`), and **Suggested fix**+ (one concrete sentence, e.g. the exact command to replace).+ - When any row needs an update, end with one line reminding the author to run+ `npx nx run twenty-agent-skills:validate` after editing the canonical content.+ - Be terse. No preamble, no sign-off. Only report genuine drift — if unsure+ whether something is user-facing, say it's uncertain rather than asserting.++ ## Step 4 — Return the verdict++ After posting the comment, return your final answer as the structured+ output the CI gate consumes:+ - `hasDrift`: `true` if at least one impacted skill file still needs updating+ (drift is NOT fully resolved by this PR); `false` if there is no skill+ impact, or every impacted file is already correctly updated in this PR.+ - `summary`: one terse sentence describing the verdict.++ Environment: GH_TOKEN is available for `gh`. The PR branch is checked out.+ settings: |+ {+ "env": {+ "GH_TOKEN": "${{ secrets.GITHUB_TOKEN }}"+ }+ }++ - name: Gate on drift verdict+ if: always()+ env:+ AGENT_OUTCOME: ${{ steps.drift-agent.outcome }}+ STRUCTURED_OUTPUT: ${{ steps.drift-agent.outputs.structured_output }}+ run: |+ if [ "$AGENT_OUTCOME" != "success" ]; then+ echo "::error::Agent skills drift checker did not complete (agent step outcome: $AGENT_OUTCOME)."+ exit 1+ fi+ if [ -z "$STRUCTURED_OUTPUT" ]; then+ echo "::error::Agent skills drift checker did not return a structured verdict."+ exit 1+ fi+ has_drift=$(printf '%s' "$STRUCTURED_OUTPUT" | jq -r '.hasDrift')+ if [ "$has_drift" = "true" ]; then+ echo "::error::Agent skills drift detected. See the agent-skills-drift-check comment on this PR."+ exit 1+ fi+ if [ "$has_drift" = "false" ]; then+ echo "No agent skills drift."+ exit 0+ fi+ echo "::error::Structured verdict present but 'hasDrift' was not a recognizable boolean: $has_drift"+ exit 1diff --git a/.github/workflows/ci-agent-skills.yaml b/.github/workflows/ci-agent-skills.yamlnew file mode 100644index 00000000000..90a9f3ac779--- /dev/null+++ b/.github/workflows/ci-agent-skills.yaml@@ -0,0 +1,199 @@+name: CI Agent Skills++on:+ push:+ branches:+ - main+ paths:+ - package.json+ - packages/twenty-agent-skills/**+ - .github/workflows/ci-agent-skills.yaml++ pull_request:++permissions:+ contents: read++concurrency:+ group: ${{ github.workflow }}-${{ github.ref }}+ cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}++jobs:+ changed-files-check:+ uses: ./.github/workflows/changed-files.yaml+ with:+ files: |+ package.json+ packages/twenty-agent-skills/**+ .github/workflows/ci-agent-skills.yaml++ agent-skills-validate:+ needs: changed-files-check+ if: needs.changed-files-check.outputs.any_changed == 'true'+ timeout-minutes: 15+ runs-on: ubuntu-latest+ steps:+ - name: Fetch local actions+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1+ with:+ fetch-depth: 10++ - name: Install dependencies+ uses: ./.github/actions/yarn-install++ - name: Agent Skills / Build and validate+ run: npx nx run twenty-agent-skills:validate++ - name: Agent Skills / Test+ run: npx nx run twenty-agent-skills:test++ - name: Agent Skills / List with the skills CLI+ run: |+ set -euo pipefail+ LISTING="$(npx -y skills@latest add ./packages/twenty-agent-skills/dist --list)"+ echo "$LISTING"++ for SKILL in create-app develop-app manage-app publish-app use-twenty-mcp; do+ grep -q "$SKILL" <<<"$LISTING" || {+ echo "::error::$SKILL missing from the collection listing"+ exit 1+ }+ done++ # The package path must scope discovery to the app skills; a listing that+ # also carries repository-wide skills means the source is wrong.+ if grep -q 'syncable-entity' <<<"$LISTING"; then+ echo "::error::listing leaked internal contributor skills"+ exit 1+ fi++ - name: Agent Skills / Install each skill independently+ run: |+ set -euo pipefail+ for SKILL in create-app develop-app manage-app publish-app use-twenty-mcp; do+ INSTALL_DIR="$(mktemp -d)"+ (+ cd "$INSTALL_DIR"+ npx -y skills@latest add "$GITHUB_WORKSPACE/packages/twenty-agent-skills/dist" \+ --skill "$SKILL" --agent claude-code --agent codex --copy -y+ )+ npx nx run twenty-agent-skills:verify:install -- "$INSTALL_DIR" "$SKILL"+ rm -rf "$INSTALL_DIR"+ done++ - name: Agent Skills / Install the whole collection+ run: |+ set -euo pipefail+ INSTALL_DIR="$(mktemp -d)"+ (+ cd "$INSTALL_DIR"+ npx -y skills@latest add "$GITHUB_WORKSPACE/packages/twenty-agent-skills/dist" \+ --skill '*' --agent claude-code --agent codex --copy -y+ )+ npx nx run twenty-agent-skills:verify:install -- "$INSTALL_DIR"+ rm -rf "$INSTALL_DIR"++ - name: Archive the verified distribution+ if: github.event_name == 'push' && github.ref == 'refs/heads/main'+ run: tar -C packages/twenty-agent-skills/dist -czf "$RUNNER_TEMP/twenty-agent-skills.tar.gz" .++ - name: Upload the verified distribution+ if: github.event_name == 'push' && github.ref == 'refs/heads/main'+ uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2+ with:+ name: twenty-agent-skills+ path: ${{ runner.temp }}/twenty-agent-skills.tar.gz+ retention-days: 1+ if-no-files-found: error++ agent-skills-publish:+ needs: agent-skills-validate+ if: github.event_name == 'push' && github.ref == 'refs/heads/main' && github.repository == 'twentyhq/twenty'+ timeout-minutes: 5+ runs-on: ubuntu-latest+ permissions:+ contents: write+ outputs:+ released: ${{ steps.publish.outputs.released }}+ steps:+ - name: Checkout repository+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1++ - name: Download the verified distribution+ uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0+ with:+ name: twenty-agent-skills+ path: ${{ runner.temp }}/agent-skills-artifact++ - name: Publish distribution branch+ id: publish+ run: |+ set -euo pipefail+ git fetch --depth=1 --no-tags origin main+ if [ "$(git rev-parse "$GITHUB_SHA:packages/twenty-agent-skills")" != "$(git rev-parse 'FETCH_HEAD:packages/twenty-agent-skills')" ]; then+ echo 'Skipping this distribution because the skills source has changed on main.'+ exit 0+ fi++ DISTRIBUTION_DIR="$RUNNER_TEMP/agent-skills-dist"+ PUBLISH_DIR="$RUNNER_TEMP/agent-skills-release"+ mkdir "$DISTRIBUTION_DIR"+ tar -xzf "$RUNNER_TEMP/agent-skills-artifact/twenty-agent-skills.tar.gz" -C "$DISTRIBUTION_DIR"++ REMOTE_BRANCH="$(git ls-remote --heads origin refs/heads/agent-skills)"+ if [ -n "$REMOTE_BRANCH" ]; then+ git fetch --no-tags origin refs/heads/agent-skills+ git worktree add --detach "$PUBLISH_DIR" FETCH_HEAD+ else+ git worktree add --detach --no-checkout "$PUBLISH_DIR"+ git -C "$PUBLISH_DIR" switch --orphan agent-skills+ fi++ rsync -a --delete --exclude=/.git "$DISTRIBUTION_DIR/" "$PUBLISH_DIR/"+ cd "$PUBLISH_DIR"+ git add --all+ if git diff --cached --quiet; then+ echo 'The agent-skills distribution is unchanged.'+ echo 'released=true' >> "$GITHUB_OUTPUT"+ exit 0+ fi++ git config user.name 'github-actions[bot]'+ git config user.email '41898282+github-actions[bot]@users.noreply.github.com'+ git commit -m "Publish agent skills from $GITHUB_SHA"+ git push origin HEAD:refs/heads/agent-skills+ echo 'released=true' >> "$GITHUB_OUTPUT"++ agent-skills-remote-source:+ needs: agent-skills-publish+ if: needs.agent-skills-publish.outputs.released == 'true'+ timeout-minutes: 15+ runs-on: ubuntu-latest+ steps:+ - name: Checkout repository+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1++ - name: Setup Node.js+ uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0+ with:+ node-version: '24'++ - name: Download the verified distribution+ uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0+ with:+ name: twenty-agent-skills+ path: ${{ runner.temp }}/agent-skills-artifact++ - name: Agent Skills / Install from the documented remote source+ run: |+ set -euo pipefail+ mkdir -p packages/twenty-agent-skills/dist+ tar -xzf "$RUNNER_TEMP/agent-skills-artifact/twenty-agent-skills.tar.gz" -C packages/twenty-agent-skills/dist+ INSTALL_DIR="$(mktemp -d)"+ (+ cd "$INSTALL_DIR"+ npx -y skills@latest add 'https://github.com/twentyhq/twenty/tree/agent-skills' \+ --skill '*' --agent claude-code --agent codex --copy -y+ )+ node packages/twenty-agent-skills/scripts/verify-install.js "$INSTALL_DIR"+ rm -rf "$INSTALL_DIR"diff --git a/.github/workflows/ci-codex-plugin.yaml b/.github/workflows/ci-codex-plugin.yamldeleted file mode 100644index 89874532b7e..00000000000--- a/.github/workflows/ci-codex-plugin.yaml+++ /dev/null@@ -1,44 +0,0 @@-name: CI Codex Plugin--on:- push:- branches:- - main-- pull_request:--permissions:- contents: read--concurrency:- group: ${{ github.workflow }}-${{ github.ref }}- cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}--jobs:- changed-files-check:- uses: ./.github/workflows/changed-files.yaml- with:- files: |- package.json- packages/twenty-codex-plugin/**- .github/workflows/ci-codex-plugin.yaml-- codex-plugin-validate:- needs: changed-files-check- if: needs.changed-files-check.outputs.any_changed == 'true'- timeout-minutes: 10- runs-on: ubuntu-latest- steps:- - name: Fetch local actions- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1- with:- fetch-depth: 10-- - name: Install dependencies- uses: ./.github/actions/yarn-install-- - name: Codex Plugin / Validate- run: npx nx run twenty-codex-plugin:validate-- - name: Codex Plugin / Test- run: npx nx run twenty-codex-plugin:testdiff --git a/.gitignore b/.gitignoreindex 12c5e96f490..64b99f55f8a 100644--- a/.gitignore+++ b/.gitignore@@ -4,7 +4,6 @@.claude/*!.claude/settings.json!.claude/skills/-.cursor/debug-*.log**/**/node_modules/.cachediff --git a/.vscode/settings.json b/.vscode/settings.jsonindex 67f3267c4d7..e2c38696f55 100644--- a/.vscode/settings.json+++ b/.vscode/settings.json@@ -52,9 +52,6 @@"**/.yarn": true},"oxc.lint.enable": true,- "files.associations": {- ".cursorrules": "markdown"- },"jestrunner.codeLensSelector": "**/*.{test,spec,integration-spec}.{js,jsx,ts,tsx}","typescript.tsdk": "node_modules/typescript/lib","typescript.experimental.useTsgo": falsediff --git a/CLAUDE.md b/CLAUDE.mdindex 8300753e6af..86c0ed959b6 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -19,8 +19,6 @@ Where this repo differs from your defaults:- Import icons from `twenty-ui/icon`, never directly from `@tabler/icons-react`; action and status concepts should use their action or status icons.- Test behavior, not implementation: query by user-visible text/roles, `@testing-library/user-event` for interactions.-Longer-form guides remain in `.cursor/rules/` (from the Cursor era).-## Commands```bashdiff --git a/README.md b/README.mdindex 63755643162..e6137b5c569 100644--- a/README.md+++ b/README.md@@ -68,6 +68,14 @@ npx twenty app:publish --privateSee the [app development guide](https://docs.twenty.com/developers/extend/apps/getting-started) for objects, views, agents, and logic functions.+Building with a coding agent? Install the official [Twenty app skills](./packages/twenty-agent-skills), which work in Claude Code, Codex, Cursor, Pi, and any other harness supported by the `skills` CLI:++```bash+npx skills add https://github.com/twentyhq/twenty/tree/agent-skills --list+```++The `agent-skills` branch is created by the first successful publish from `main`. Until then, use the [local build instructions](./packages/twenty-agent-skills#local-development). [`SKILLS.md`](./SKILLS.md) explains the other skill families in this repository and who they are for.+### <img src="./packages/twenty-website/public/images/readme/rocket-icon.svg" width="14" height="14"/> Self-hostingRun Twenty on your own infrastructure with [Docker Compose](https://docs.twenty.com/developers/self-host/capabilities/docker-compose), or contribute locally via the [local setup guide](https://docs.twenty.com/developers/contribute/capabilities/local-setup).diff --git a/SKILLS.md b/SKILLS.mdnew file mode 100644index 00000000000..14209f90828--- /dev/null+++ b/SKILLS.md@@ -0,0 +1,40 @@+# Agent Skills in this repository++This repository contains several families of Agent Skills. They have different audiences, so pick the one that matches what you are doing. Only the first family is meant to be installed by people building on Twenty.++## Building a Twenty app — install these++[`packages/twenty-agent-skills`](./packages/twenty-agent-skills) is the official, harness-agnostic collection for creating, developing, operating, and publishing Twenty apps. It works in Claude Code, Codex, Cursor, Pi, and any other harness supported by the `skills` CLI, against any Twenty instance including self-hosted and localhost.++```bash+npx skills add https://github.com/twentyhq/twenty/tree/agent-skills --list+npx skills add https://github.com/twentyhq/twenty/tree/agent-skills --skill create-app+```++Install from the `agent-skills` branch, which contains only the built app skills and Codex plugin. The source package on `main` keeps references shared and must be built before installation. The branch becomes available after the first successful publish from `main`; until then, use the [local build instructions](./packages/twenty-agent-skills#local-development).++| Skill | Use it for |+| ---------------- | ------------------------------------------------------------------------------------- |+| `create-app` | Scaffold a new Twenty app. |+| `develop-app` | Add or modify objects, fields, logic functions, layouts, front components, workflows. |+| `manage-app` | Remotes, sync, build, deploy, logs, troubleshooting, CI/CD. |+| `publish-app` | README, marketplace metadata, logos, screenshots, public assets. |+| `use-twenty-mcp` | Optional: connect an agent to a workspace over MCP and present records readably. |++## Working inside a Twenty workspace++[`packages/twenty-claude-skills`](./packages/twenty-claude-skills) holds skills for using a Twenty workspace rather than building on it, such as presenting CRM records as readable summaries.++## Contributing to Twenty itself++[`.claude/skills`](./.claude/skills) holds the skills for agents and contributors working in this checkout: `qa-scout` for browser QA of a pull request, and the `syncable-entity-*` series covering Twenty's own workspace migration system. They assume a checkout of this repository and are not useful for app development, which the `syncable-entity-*` descriptions state in their first sentence.++These are what a bare-repository listing (`npx skills add twentyhq/twenty --list`) returns. Use the `agent-skills` branch above for app development.++## Shipped inside apps++`packages/twenty-apps/**/src/skills` holds skills that a specific Twenty app ships to its users. They are part of that app, not of this collection.++## Codex plugin++[`packages/twenty-agent-skills`](./packages/twenty-agent-skills) owns both the canonical skills and the Codex metadata. Its build produces one distribution, published at the root of the `agent-skills` branch, for the `skills` CLI and the Codex plugin named `twenty`. Generated copies are not committed to `main`.diff --git a/package.json b/package.jsonindex 054ffbdf9bb..1ab56c24c47 100644--- a/package.json+++ b/package.json@@ -82,7 +82,7 @@"packages/twenty-client-sdk","packages/twenty-cli","packages/create-twenty-app",- "packages/twenty-codex-plugin",+ "packages/twenty-agent-skills","packages/twenty-oxlint-rules","packages/twenty-claude-skills"]diff --git a/packages/twenty-codex-plugin/.codex-plugin/plugin.json b/packages/twenty-agent-skills/.codex-plugin/plugin.jsonsimilarity index 100%rename from packages/twenty-codex-plugin/.codex-plugin/plugin.jsonrename to packages/twenty-agent-skills/.codex-plugin/plugin.jsondiff --git a/packages/twenty-codex-plugin/.gitignore b/packages/twenty-agent-skills/.gitignoresimilarity index 72%rename from packages/twenty-codex-plugin/.gitignorerename to packages/twenty-agent-skills/.gitignoreindex 47e623723e5..38a08f465e5 100644--- a/packages/twenty-codex-plugin/.gitignore+++ b/packages/twenty-agent-skills/.gitignore@@ -1 +1,2 @@.mcp.local.json+dist/diff --git a/packages/twenty-codex-plugin/.mcp.json b/packages/twenty-agent-skills/.mcp.jsonsimilarity index 100%rename from packages/twenty-codex-plugin/.mcp.jsonrename to packages/twenty-agent-skills/.mcp.jsondiff --git a/packages/twenty-agent-skills/.prettierignore b/packages/twenty-agent-skills/.prettierignorenew file mode 100644index 00000000000..849ddff3b7e--- /dev/null+++ b/packages/twenty-agent-skills/.prettierignore@@ -0,0 +1 @@+dist/diff --git a/packages/twenty-codex-plugin/AGENTS.md b/packages/twenty-agent-skills/AGENTS.mdsimilarity index 59%rename from packages/twenty-codex-plugin/AGENTS.mdrename to packages/twenty-agent-skills/AGENTS.mdindex 9c1ad1ee63b..01e0f97f3cb 100644--- a/packages/twenty-codex-plugin/AGENTS.md+++ b/packages/twenty-agent-skills/AGENTS.md@@ -19,37 +19,30 @@ A Twenty app is a standalone npm package that extends a running Twenty instance.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` |+| 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.+The cross-skill rules live in `references/concepts/operating-rules.md`. That file is the single source of truth: the build includes it in the shared distribution and the individual skill bundles, so all installations use the same authored rules. Read it before any non-trivial task, and do not restate or fork it here.-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.+Codex-specific additions on top of those rules:-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.--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.+- Workspace MCP endpoints belong in the user's local `.mcp.json` and Codex MCP config. This plugin only ships the public `twenty-docs` MCP server. Use `scripts/setup-mcp.sh` to configure a workspace MCP endpoint for a specific user.## Reference Doc MapWhen 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.+- `concepts/operating-rules.md` — the durable cross-skill rules. Authoritative; nothing restates them.- `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.@@ -66,8 +59,8 @@ When a skill points at a reference, read only what the task needs:## 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.+When editing the source package, run `npx nx run twenty-agent-skills:validate` and `npx nx run twenty-agent-skills:build` after changes. 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`.+This file is for _agents using the plugin_. If you are _editing the plugin itself_, see [`CONTRIBUTING.md`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-agent-skills/CONTRIBUTING.md).diff --git a/packages/twenty-codex-plugin/CHANGELOG.md b/packages/twenty-agent-skills/CHANGELOG.mdsimilarity index 82%rename from packages/twenty-codex-plugin/CHANGELOG.mdrename to packages/twenty-agent-skills/CHANGELOG.mdindex 0b079490c09..0dc05bde739 100644--- a/packages/twenty-codex-plugin/CHANGELOG.md+++ b/packages/twenty-agent-skills/CHANGELOG.md@@ -1,16 +1,27 @@# Changelog-All notable changes to the Twenty Codex plugin are documented in this file.+All notable changes to Twenty Agent Skills and its Codex plugin are documented in this file.The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).-Entries reference the canonical skills (`create-app`, `develop-app`, `manage-app`, `publish-app`, `use-twenty-mcp`) and the validation script (`scripts/validate.js`).+Entries reference the canonical skills (`create-app`, `develop-app`, `manage-app`, `publish-app`, `use-twenty-mcp`) and the validation script (`scripts/validate-source.js`).++## [Unreleased]++### Changed++- Consolidated canonical skills, shared references, and Codex metadata into `packages/twenty-agent-skills`, replacing the separate source and generated packages. The Codex plugin identifier remains `twenty`.+- Build one distribution in ignored `dist/` for both the `skills` CLI and Codex. Individual skills contain their required references; only the publishing branch contains generated copies.+- Publish the built distribution at the root of the `agent-skills` branch from `main`. Installation instructions use that branch and explain local installation before the first publish.+- Unified source validation, distribution validation, installation checks, and CI under `twenty-agent-skills`.## [0.1.0] - UnreleasedThe first version of the Twenty Codex plugin.### Added++- `references/concepts/operating-rules.md`: the durable cross-skill rules, harness-neutral and authoritative. `AGENTS.md` and the four app skills link to it instead of restating it, and `assertOperatingRulesSingleSource` fails validation when any of them forks a rule.- `AGENTS.md` at the plugin root: durable cross-skill operating rules, skill routing table, and reference-doc map.- `CHANGELOG.md` (this file).- `CHECKLIST.md`: best-practices compliance matrix mapping each official Codex plugin requirement to an automated check or a manual sign-off.@@ -24,9 +35,12 @@ The first version of the Twenty Codex plugin.- `.github/workflows/ci-codex-plugin.yaml`: CI workflow running `validate` and `test` on PRs touching the plugin.### Changed+- `scripts/validate.js` refactored from a single 760-line file into a thin entry point plus focused modules under `scripts/validators/` (`lib`, `metadata`, `assets`, `skills`, `references`, `cross-doc-contracts`, `setup-helper`).- `package.json`: exposed `test` script; added `AGENTS.md`, `CHANGELOG.md`, `CHECKLIST.md`, `CONTRIBUTING.md`, `templates` to `files`.- `.codex-plugin/plugin.json`: rewrote `interface.longDescription` into 3 scannable sentences (was a single ~400-char sentence).+- `references/use-twenty-mcp/setup.md`: rewritten as multi-harness MCP setup (Codex, Claude Code, Cursor, generic clients) with self-hosted and localhost workspaces as first-class targets.+- `skills/use-twenty-mcp/SKILL.md`, `skills/publish-app/SKILL.md`: harness-neutral wording; the public `twenty-docs` MCP server is an optional enhancement rather than an assumed dependency.- `README.md`: restructured into What/Installation/Skills/MCP/Development sections; added skills-overview table; linked `CONTRIBUTING.md`, `CHECKLIST.md`, `CHANGELOG.md`.- `scripts/validators/lib.js` `isAllowedDocumentationHost`: added `developers.openai.com`, `keepachangelog.com`, `semver.org` to the placeholder host allowlist so external documentation references in `CHECKLIST.md`, `CONTRIBUTING.md`, and `CHANGELOG.md` pass validation.- `references/develop-app/tests.md` and `references/manage-app/cli-and-sync.md`: documented that integration tests must run against the isolated test instance (`yarn twenty docker:start --test`, port `2021`) instead of the dev instance, since the test harness installs and uninstalls the app on its target server.@@ -35,12 +49,14 @@ The first version of the Twenty Codex plugin.- `references/develop-app/app-structure.md`, `skills/develop-app/SKILL.md`, `references/develop-app/logic.md`, `references/develop-app/front-components.md`: made the one-export-per-file rule explicit — every helper, type, and client file exports exactly one thing, and multiple function exports in a single file are forbidden. The rule counts exports, not declarations: a local, non-exported type may live alongside the util, but an exported or reused type splits into `src/types/<name>.ts` separate from `src/utils/<name>.util.ts`.### Plugin Structure+- `.codex-plugin/plugin.json` manifest with `interface` metadata (display name, descriptions, category, capabilities, branding, default prompts).- `package.json` declaring the workspace package and listing shipped files.- `.mcp.json` declaring only the public `twenty-docs` MCP server at `https://docs.twenty.com/mcp`.- `assets/twenty-logo.png` and `assets/twenty-logo.svg` for marketplace branding.### Skills (`skills/`)+- `create-app` — scaffold a new Twenty app via `create-twenty-app`, with prompts for the Twenty instance URL and Docker vs existing-instance choice.- `develop-app` — add or modify Twenty app entities (objects, fields, logic functions, roles, views, layouts, skills, agents, connection providers, front components); enforces `yarn twenty dev:add` for entity generation and one-shot `yarn twenty dev --once` sync.- `manage-app` — remotes, sync, build, deploy, logs, function execution, uninstall, and CI/CD for existing apps; requires explicit confirmation for production-affecting operations.@@ -49,6 +65,7 @@ The first version of the Twenty Codex plugin.- Per-skill `agents/openai.yaml` with `display_name`, `short_description` (≤64 chars), and `default_prompt` that mentions `$<skill-name>`.### References (`references/`)+- `concepts/how-apps-work.md` — foundational SDK packages, remotes, sync lifecycle, front component rendering, app file structure, key concepts (linked from every skill).- `develop-app/app-structure.md`, `data-model.md`, `front-components.md`, `layout.md`, `standalone-pages.md`, `logic.md`, `workflows.md`, `tests.md` — entity creation, file structure, validation checklist, full-page UI patterns, runtime verification.- `design/front-component-ui.md` — visual design rules, Twenty UI defaults, design tokens, component selection.@@ -59,5 +76,6 @@ The first version of the Twenty Codex plugin.- `use-twenty-mcp/result-formatting.md` — record link building, date formatting, readable Markdown contract.### Tooling+- `scripts/setup-mcp.sh` — helper to register a user-local workspace MCP endpoint with Codex; normalizes workspace URLs (adds `https://`, `/mcp` suffix), derives sensible MCP server names, supports localhost and custom domains, integrates with `codex mcp add` and OAuth.- `scripts/validate.js` — single-file validation script enforcing version sync, no bundled workspace MCP, no secrets/non-placeholder URLs, canonical skill names, required SKILL.md + `agents/openai.yaml` shape, required reference files, cross-doc contracts (MCP formatting, front-component guidance, CLI guidance split, foundational concepts linkage), and `setup-mcp.sh` syntax + URL-normalization correctness.diff --git a/packages/twenty-agent-skills/CHECKLIST.md b/packages/twenty-agent-skills/CHECKLIST.mdnew file mode 100644index 00000000000..d9a06667795--- /dev/null+++ b/packages/twenty-agent-skills/CHECKLIST.md@@ -0,0 +1,113 @@+# Twenty Codex Plugin — Best Practices Compliance Checklist++This file is the authoritative compliance matrix. Every row maps an official requirement (Codex build guide, Codex best-practices guide, or OpenAI reference implementation) to either an **automated** check (a `scripts/validate-source.js` assertion function) or a **manual** sign-off.++A release is shippable when:++1. `npx nx run twenty-agent-skills:validate` and `npx nx run twenty-agent-skills:build` exit 0 (source and distribution checks pass).+2. Every `[manual]` row has a current sign-off date.++## Sources of Truth++- **Codex Plugin Build Guide** — https://developers.openai.com/codex/plugins/build+- **Codex Best Practices** — https://developers.openai.com/codex/learn/best-practices+- **Reference Implementation** — https://github.com/openai/codex-plugin-cc++## Plugin Manifest (`.codex-plugin/plugin.json`)++| # | Requirement | Source | Check |+| --- | ----------------------------------------------------------------------- | ---------------------------- | ----------------------------------------------------------------------- |+| M1 | `name` present, kebab-case, lowercase | Build guide §Naming | [automated] `assertJsonMetadata` |+| M2 | `version` follows SemVer and matches `package.json` | Build guide §Manifest | [automated] `assertJsonMetadata` |+| M3 | `description` present and concise | Build guide §Required fields | [automated] `assertInterfaceFields` (planned) |+| M4 | `mcpServers` points at `./.mcp.json` | Build guide §MCP | [automated] `assertJsonMetadata` |+| M5 | `skills` points at `./skills/` | Build guide §Skills | [automated] `assertJsonMetadata` |+| M6 | `interface.displayName` present and non-empty | Build guide §Interface | [automated] `assertInterfaceFields` (planned) |+| M7 | `interface.shortDescription` ≤ 64 chars | Build guide §Marketplace | [automated] `assertInterfaceFields` (planned) |+| M8 | `interface.longDescription` present, multi-sentence | Build guide §Marketplace | [automated] `assertInterfaceFields` (planned) |+| M9 | `interface.category` matches marketplace enum (`Coding`) | Build guide §Marketplace | [automated] `assertInterfaceFields` (planned) |+| M10 | `interface.capabilities` non-empty subset of `Interactive,Read,Write` | Build guide §Capabilities | [automated] `assertInterfaceFields` (planned) |+| M11 | `interface.websiteURL`, `privacyPolicyURL`, `termsOfServiceURL` present | Build guide §Publisher links | [automated] `assertInterfaceFields` (planned) |+| M12 | `interface.brandColor` matches `#RRGGBB` and reflects Twenty brand | Build guide §Marketplace | [automated] `assertInterfaceFields` (planned), [manual] brand alignment |+| M13 | `interface.defaultPrompt` is a non-empty array of strings | Build guide §Defaults | [automated] `assertInterfaceFields` (planned) |+| M14 | All manifest paths start with `./` and stay within plugin root | Build guide §Paths | [automated] `assertJsonMetadata` |++## Assets (`assets/`)++| # | Requirement | Source | Check |+| --- | ------------------------------------------------------------- | ------------------------ | ---------------------------------------------------- |+| A1 | `interface.logo` exists and is PNG | Build guide §Assets | [automated] `assertAssets` (planned) |+| A2 | Logo PNG is ≥ 256×256 | Build guide §Assets | [automated] `assertAssets` (planned, PNG IHDR parse) |+| A3 | `interface.composerIcon` exists and is valid SVG or PNG | Build guide §Assets | [automated] `assertAssets` (planned) |+| A4 | `interface.screenshots` has ≥ 1 entry | Build guide §Assets | [automated] `assertAssets` (planned) |+| A5 | Every screenshot path exists and is PNG | Build guide §Assets | [automated] `assertAssets` (planned) |+| A6 | Screenshots show the plugin in action (not placeholder mocks) | Build guide §Marketplace | [manual] reviewer sign-off |++## Skills (`skills/<name>/SKILL.md`)++| # | Requirement | Source | Check |+| --- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------- |+| S1 | Canonical five skills present | Internal convention | [automated] `assertSkills` |+| S2 | No legacy skill names anywhere | Internal convention | [automated] `assertNoLegacySkillReferences` |+| S3 | Each `SKILL.md` has YAML frontmatter with `name` + `description` only | Build guide §Skills | [automated] `assertSkills` |+| S4 | Frontmatter `name` matches directory | Build guide §Skills | [automated] `assertSkills` |+| S5 | Each skill has `agents/openai.yaml` with `display_name`, `short_description` (≤64), `default_prompt` (mentions `$<skill>`) | OpenAI Agent format | [automated] `assertSkills` |+| S6 | Each skill is scoped to a single job with clear boundaries | Best practices §Skill scope | [manual] cross-skill audit |+| S7 | Each skill includes a `## When to use` trigger-phrase section | Best practices §Descriptions | [automated] `assertSkillTriggerPhrases` (planned) |+| S8 | Descriptions are disjoint across skills (no routing collision) | Best practices §Descriptions | [manual] cross-skill audit |++## References (`references/`)++| # | Requirement | Source | Check |+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ----------------------------------------------- |+| R1 | All required reference files exist | Internal convention | [automated] `assertReferences` |+| R2 | `use-twenty-mcp` formatting contract intact across SKILL.md and result-formatting.md | Internal convention | [automated] `assertTwentyMcpFormattingContract` |+| R3 | Front component guidance correctly split across develop-app skill, layout.md, front-components.md, standalone-pages.md, app-structure.md, front-component-ui.md | Internal convention | [automated] `assertFrontComponentGuidance` |+| R4 | CLI guidance correctly split between develop-app and manage-app | Internal convention | [automated] `assertCliGuidanceSplit` |+| R5 | `concepts/how-apps-work.md` is foundational and linked from every skill | Internal convention | [automated] `assertHowAppsWork` |++## MCP (`.mcp.json` and `scripts/setup-mcp.sh`)++| # | Requirement | Source | Check |+| ---- | --------------------------------------------------------- | --------------------- | -------------------------------------- |+| MCP1 | `.mcp.json` declares only the public `twenty-docs` server | Internal convention | [automated] `assertJsonMetadata` |+| MCP2 | No workspace-specific MCP configs bundled anywhere | Internal convention | [automated] `assertNoBundledMcpConfig` |+| MCP3 | No bearer tokens or API keys anywhere in the package | Build guide §Security | [automated] `assertNoBundledMcpConfig` |+| MCP4 | No non-placeholder URLs in any file | Internal convention | [automated] `assertNoBundledMcpConfig` |+| MCP5 | `scripts/setup-mcp.sh` passes `bash -n` syntax check | Internal convention | [automated] `assertSetupHelper` |+| MCP6 | `setup-mcp.sh` correctly normalizes representative URLs | Internal convention | [automated] `assertSetupHelper` |++## Marketplace & Distribution++| # | Requirement | Source | Check |+| --- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- | --------------------------------------- |+| D1 | `templates/marketplace.example.json` has marketplace identity, plugin name/category, a local distribution source, and valid policies | Codex marketplace schema | [automated] `assertMarketplaceTemplate` |+| D2 | Optional repo-level `.agents/plugins/marketplace.json` points at `./packages/twenty-agent-skills/dist` | Build guide §Distribution | [automated] `assertJsonMetadata` |+| D3 | `CHANGELOG.md` updated for every version bump | Reference impl | [manual] release reviewer sign-off |++## Process++| # | Requirement | Source | Check |+| --- | --------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------- |+| P1 | `validate-source.js` runs in CI on every PR touching the plugin | Reference impl | [manual] confirm `.github/workflows/ci-agent-skills.yaml` is active |+| P2 | `validate-source.js` has its own unit tests | Internal convention | [manual] confirm `scripts/__tests__/` exists and runs |+| P3 | Version bump procedure documented | Internal convention | [manual] confirm `CONTRIBUTING.md` covers it |++## Manual Sign-off Log++When a manual row above is verified, add a line here.++| Date | Row(s) | Reviewer | Notes |+| ---------- | ------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| 2026-05-28 | S6, S8 | Codex plugin compliance pass | Skill descriptions reviewed side-by-side; "When To Use" sections added to all five SKILL.md files with explicit "do not use this skill for X" boundary callouts referencing the four siblings. Routing surface is disjoint. |+| 2026-05-28 | M12 | Codex plugin compliance pass | `brandColor: #000000` matches the actual logo background in `assets/twenty-logo.svg`. |++## Deferred Items++Tracked for a follow-up PR; not blocking the current release.++| Item | Reason for deferral |+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Real marketplace screenshots (A4, A5, A6) | Requires real captures against a demo workspace. `assets/screenshots/README.md` documents what's needed; `plugin.json` `screenshots` stays `[]` until the PNGs land so `assertAssets` does not regress. |+| Splitting `standalone-pages.md` / `front-component-ui.md` | The cross-doc contracts assert dozens of exact fragments per file. The mechanical risk of fragment drift outweighs the readability gain at current size (~450 lines each). Re-evaluate when either exceeds 600 lines. |+| `hooks/hooks.json` SessionStart hook | The Codex hook schema for plugin-bundled hooks needs deeper validation; a misconfigured `SessionStart` hook would fire on every Codex session. Add only when the format is verified against a working reference implementation. |diff --git a/packages/twenty-agent-skills/CONTRIBUTING.md b/packages/twenty-agent-skills/CONTRIBUTING.mdnew file mode 100644index 00000000000..96855b96955--- /dev/null+++ b/packages/twenty-agent-skills/CONTRIBUTING.md@@ -0,0 +1,59 @@+# Contributing++This package is the canonical source for Twenty app skills and the Codex plugin. Agents using the plugin should read [`AGENTS.md`](./AGENTS.md).++## Source and Distribution++Edit `skills/<name>/SKILL.md` and shared `references/` directly. Keep this content harness-neutral. Codex-specific behavior belongs in `.codex-plugin/`, `.mcp.json`, `agents/openai.yaml`, and `scripts/setup-mcp.sh`.++`build` creates ignored `dist/` with self-contained skill directories, the shared references needed by `AGENTS.md`, and Codex metadata. Both the `skills` CLI and Codex install that distribution. Never edit or commit generated files to `main`.++The main-only publishing workflow validates and builds this package, then publishes the contents of `dist/` at the root of the `agent-skills` branch. That branch is created on the first successful publish after merge. Until then, install from the local build as described in [`README.md`](./README.md#local-development). Codex marketplace entries should select this same published branch; the local template selects `./packages/twenty-agent-skills/dist`.++## Checks++Run from the repository root:++```bash+npx nx run twenty-agent-skills:validate+npx nx run twenty-agent-skills:build+npx nx run twenty-agent-skills:test+```++All must pass before merge. Build validation checks that references remain within each installed skill. Scripts use Node built-ins only; no new runtime dependencies.++For an actual installation check, install the built distribution into an isolated directory with the `skills` CLI, then verify its installed copies:++```bash+npx nx run twenty-agent-skills:verify:install -- "<install-directory>" create-app+```++Omit skill names to verify all five. CI exercises both single-skill and all-skill installs. Changes affecting scaffold or sync guidance also need the manual procedure in [`SMOKE-TEST.md`](./SMOKE-TEST.md).++## Adding a Skill++1. Create `skills/<name>/SKILL.md` (frontmatter: `name`, `description` only) and `skills/<name>/agents/openai.yaml` (`display_name`, `short_description` ≤ 64, `default_prompt` mentioning `$<name>`).+2. Add a `## When To Use` section with 4–6 user-language triggers and “do not use this skill for X” callouts referencing siblings.+3. Add the name to `CANONICAL_SKILL_NAMES` in `scripts/validators/lib.js`.++## Adding a Reference++1. Place it under `references/<area>/<name>.md` and link it from the skills that need it. The build follows these links to bundle each skill's references.+2. Add the path to `REQUIRED_REFERENCES` in `scripts/validators/references.js`.+3. If the file participates in a cross-doc contract, update `scripts/validators/cross-doc-contracts.js` in the same commit.++## Bumping the Version++Update `package.json` and `.codex-plugin/plugin.json` together. Then move unreleased entries in `CHANGELOG.md` under a new `[X.Y.Z] - YYYY-MM-DD` heading.++SemVer: **patch** for copy/validation fixes, **minor** for new references/rules/skill sections, **major** for renaming a canonical skill or breaking the frontmatter/agents.yaml shape.++The public Codex plugin identifier remains `twenty`; it does not follow the workspace package name.++## Editing Validators++Add source assertions in the appropriate `scripts/validators/*.js` module and call them from `scripts/validate-source.js`. Add passing and failing fixtures in `scripts/__tests__/source-validation.spec.js`. Distribution checks live in `scripts/validate-distribution.js`, with fixtures in `scripts/__tests__/distribution-validation.spec.js`.++## PRs++One concern per PR. Title prefix: `feat|fix|docs|chore(agent-skills):`. Mention the relevant checks and any [`CHECKLIST.md`](./CHECKLIST.md) rows touched.diff --git a/packages/twenty-agent-skills/README.md b/packages/twenty-agent-skills/README.mdnew file mode 100644index 00000000000..c1d73e7236a--- /dev/null+++ b/packages/twenty-agent-skills/README.md@@ -0,0 +1,105 @@+# Twenty Agent Skills++Official [Agent Skills](https://skills.sh/) for building Twenty apps, shared by the `skills` CLI and the Codex plugin named `twenty`.++This package owns the five canonical skills, shared references, and Codex metadata. One build produces a distribution with self-contained skill directories for both installation methods. Generated files live in ignored `dist/` locally and on the `agent-skills` publishing branch, never in the source tree on `main`.++## Installation++### Agent Skills++Install into Claude Code, Codex, Cursor, Pi, or any other harness supported by the `skills` CLI:++```bash+# List the available skills+npx skills add https://github.com/twentyhq/twenty/tree/agent-skills --list++# Install one skill+npx skills add https://github.com/twentyhq/twenty/tree/agent-skills --skill create-app+npx skills add https://github.com/twentyhq/twenty/tree/agent-skills --skill develop-app++# Install everything+npx skills add https://github.com/twentyhq/twenty/tree/agent-skills --skill '*'+```++The CLI prompts for target agents, or accepts `--agent` (for example `--agent claude-code`, `--agent codex`, or `--agent '*'`). Each installed skill includes the references it needs.++**First publish:** the `agent-skills` branch is created by the first successful publish from `main`. Before that workflow has run, use the [local build](#local-development) below. The source package on `main` is not directly installable with the `skills` CLI because its references are shared across skills.++Use the branch URL above to select the app-development collection. The bare `twentyhq/twenty` repository also contains contributor and app-specific skills; see the repository's [`SKILLS.md`](https://github.com/twentyhq/twenty/blob/main/SKILLS.md) for those audiences.++### Codex Plugin++Search for “Twenty” in the Codex plugin directory and install. The plugin keeps its public identifier, `twenty`, and consumes the same built distribution as the `skills` CLI. It also includes the public Twenty documentation MCP server and a workspace MCP setup helper.++For a checkout or an unpublished change, use the local marketplace instructions below.++## Skills++| Skill | Use it for |+| ---------------------------------------------------- | ------------------------------------------------------------------------------------- |+| [`create-app`](./skills/create-app/SKILL.md) | Scaffold a new Twenty app with `create-twenty-app`. |+| [`develop-app`](./skills/develop-app/SKILL.md) | Add or modify objects, fields, logic functions, layouts, front components, workflows. |+| [`manage-app`](./skills/manage-app/SKILL.md) | Manage remotes, sync, build, deploy, logs, troubleshooting, CI/CD. |+| [`publish-app`](./skills/publish-app/SKILL.md) | Prepare README, marketplace metadata, logos, screenshots, public assets. |+| [`use-twenty-mcp`](./skills/use-twenty-mcp/SKILL.md) | Connect to a workspace over MCP and present records as readable Markdown. |++The four app-development skills work without MCP setup. Self-hosted instances, custom HTTPS domains, and localhost HTTP URLs are supported. Workspace URLs and credentials stay user-local.++Cross-skill operating rules live in [`references/concepts/operating-rules.md`](./references/concepts/operating-rules.md). [`AGENTS.md`](./AGENTS.md) adds Codex-specific routing and wrapper guidance.++## MCP Setup++The Codex plugin bundles the public `twenty-docs` server for searching official Twenty documentation. Workspace data access requires each user's own MCP endpoint in their private client configuration.++From a repository checkout:++```bash+bash packages/twenty-agent-skills/scripts/setup-mcp.sh myworkspace.twenty.com+```++The helper accepts Twenty subdomains, custom domains, and localhost. It normalizes the URL to an `/mcp` endpoint and names the server after its host, such as `twenty-myworkspace`. Codex may open OAuth automatically; if it does not, run `codex mcp login <server-name>`. Use `--force-login` only for terminal-only setup.++Equivalent manual setup:++```bash+codex mcp add twenty-myworkspace --url https://myworkspace.twenty.com/mcp+codex mcp login twenty-myworkspace+```++The same helper is included at `scripts/setup-mcp.sh` in the built distribution. For other clients, see [`references/use-twenty-mcp/setup.md`](./references/use-twenty-mcp/setup.md).++Workspace MCP URLs and ChatGPT app declarations are user-local. This distribution ships no `.app.json`; a workspace MCP URL alone is not a ChatGPT connector ID.++## Local Development++Run from the repository root:++```bash+# Validate canonical skills and Codex metadata+npx nx run twenty-agent-skills:validate++# Build the shared distribution into ignored dist/+npx nx run twenty-agent-skills:build++# Install from that distribution+npx skills add ./packages/twenty-agent-skills/dist --skill create-app++# Run build and validation tests+npx nx run twenty-agent-skills:test+```++For local Codex plugin installation, build first, then copy the marketplace template (or merge its entry into an existing config):++```bash+mkdir -p .agents/plugins+cp packages/twenty-agent-skills/templates/marketplace.example.json .agents/plugins/marketplace.json+```++The template points at `./packages/twenty-agent-skills/dist`. Enable it through the Codex plugin manager. Adjust the path if the marketplace config is outside this checkout.++Edit `skills/` and `references/` directly; they are the canonical source. Keep content harness-neutral and Codex-specific settings in `.codex-plugin/`, `.mcp.json`, `agents/openai.yaml`, and `scripts/setup-mcp.sh`. Rebuild after edits; do not commit `dist/`.++The publish workflow builds and validates `main`, then publishes `dist/` at the root of the `agent-skills` branch. Pull requests validate the distribution without publishing it. See [`CONTRIBUTING.md`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-agent-skills/CONTRIBUTING.md) for the full checks and release process, [`CHECKLIST.md`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-agent-skills/CHECKLIST.md) for Codex checks, and [`CHANGELOG.md`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-agent-skills/CHANGELOG.md) for changes.++Installation is checked in CI. The workflow against a running self-hosted Twenty instance is checked separately; see [`SMOKE-TEST.md`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-agent-skills/SMOKE-TEST.md) for the procedure and its recorded run.diff --git a/packages/twenty-agent-skills/SMOKE-TEST.md b/packages/twenty-agent-skills/SMOKE-TEST.mdnew file mode 100644index 00000000000..3664c56178c--- /dev/null+++ b/packages/twenty-agent-skills/SMOKE-TEST.md@@ -0,0 +1,82 @@+# Self-Hosted Smoke Test++The portable skills claim that a user can scaffold and develop a Twenty app against a self-hosted instance. This is how that claim is checked by hand. CI covers installation (`ci-agent-skills.yaml`); this covers the workflow the installed skills describe, which needs a running Twenty instance and cannot run on a CI runner.++Run it when `create-app`, `develop-app`, or `manage-app` guidance changes in a way that affects the scaffold or sync flow.++## Install the Distribution++Build from a checkout and install the skills into the agent used for this run:++```bash+npx nx run twenty-agent-skills:build+npx skills add ./packages/twenty-agent-skills/dist --skill create-app develop-app manage-app+```++After the first successful publish from `main`, the same distribution is available at `https://github.com/twentyhq/twenty/tree/agent-skills`. Record the source revision and installation method with each new run. The recorded run below predates the distribution migration and documents the app workflow only.++## 1. Bring up a self-hosted instance++Any instance works. For a local one from a checkout of this repository:++```bash+bash packages/twenty-utils/setup-dev-env.sh+npx nx database:reset twenty-server # init only builds the schema; reset also seeds+npx nx start twenty-server+```++Wait for `http://localhost:3000/healthz` to return 200. This instance is self-hosted for the purposes of the test: a non-`twenty.com` host, over plain HTTP, on a port the user chose.++## 2. Authenticate a remote++The scaffolder reuses an existing remote's credentials when one matches the target URL, which is what makes the rest of the run non-interactive. Add one with an API key from the instance's settings:++```bash+yarn twenty remote:add --url http://localhost:3000 --api-key <api-key> --as selfhosted+```++`DEV_API_KEY` in `twenty-sdk` does not work here. It is signed for the `twenty-app-dev` Docker image's `APP_SECRET`, so a locally built server with its own secret rejects it as `Token invalid`.++## 3. Scaffold, following `create-app`++```bash+npx create-twenty-app@latest smoke-crm --url http://localhost:3000 \+ --name smoke-crm --display-name "Smoke CRM" --description "Self-hosted smoke test app"+```++Expect `Authenticating -> Reusing existing credentials`, then `Application created successfully`. Confirm the app registered on the instance rather than only on disk:++```sql+select id, "universalIdentifier", version from core.application;+```++One row must carry the `APPLICATION_UNIVERSAL_IDENTIFIER` from the generated `src/constants/universal-identifiers.ts`.++## 4. Develop, following `develop-app`++```bash+cd smoke-crm+yarn twenty dev:add object # interactive; needs a TTY+yarn twenty apply+```++`apply` prints a plan and then `Synced <app name>`. Confirm the entity reached the instance:++```sql+select "nameSingular", "namePlural" from core."objectMetadata" where "nameSingular" = 'ticket';+select table_schema || '.' || table_name from information_schema.tables where table_name ilike '%ticket%';+```++Both must return a row. The second proves the workspace migration ran and the physical table exists, which a successful sync message alone does not.++## Recorded run++Executed against a locally built server on `http://localhost:3000`, Node 24.16.0:++- Scaffold reused the `selfhosted` remote credentials, no browser OAuth, and reported `Application created successfully`.+- `core.application` carried the scaffolded identifier `e606ca1a-4035-4c20-87ac-f49e5af6f05c` at `0.1.0`.+- `dev:add object` generated `src/objects/ticket.ts` plus its view, record-page fields, navigation menu item, and record page layout.+- `yarn twenty apply` reported `Plan: 50 to add, 0 to change, 0 to destroy` and `Synced Smoke CRM (5 files)`.+- `core."objectMetadata"` held `ticket` / `tickets`, `core."navigationMenuItem"` held `ticket`, and the physical table `_ticket` existed in the workspace schema.++Note for whoever runs this next: `create-twenty-app` still calls `yarn twenty dev --once` internally during its install step, while the skills direct agents to `yarn twenty apply`. That is the scaffolder's own behavior, not skill guidance.diff --git a/packages/twenty-codex-plugin/assets/screenshots/README.md b/packages/twenty-agent-skills/assets/screenshots/README.mdsimilarity index 90%rename from packages/twenty-codex-plugin/assets/screenshots/README.mdrename to packages/twenty-agent-skills/assets/screenshots/README.mdindex 940c56c9320..17d6a748503 100644--- a/packages/twenty-codex-plugin/assets/screenshots/README.md+++ b/packages/twenty-agent-skills/assets/screenshots/README.md@@ -21,7 +21,7 @@ Three screenshots, all PNG, at marketplace resolution (preferably 1600×1000 or"./assets/screenshots/03-use-twenty-mcp.png"]```-3. Run `yarn workspace twenty-codex-plugin validate` — the planned `assertAssets` check confirms every referenced screenshot exists and is PNG.+3. Run `npx nx run twenty-agent-skills:validate` — the planned `assertAssets` check confirms every referenced screenshot exists and is PNG.4. Tick rows A4, A5, A6 in `CHECKLIST.md` with the reviewer's date.## What Not to Includediff --git a/packages/twenty-codex-plugin/assets/twenty-logo.png b/packages/twenty-agent-skills/assets/twenty-logo.pngsimilarity index 100%rename from packages/twenty-codex-plugin/assets/twenty-logo.pngrename to packages/twenty-agent-skills/assets/twenty-logo.pngdiff --git a/packages/twenty-codex-plugin/assets/twenty-logo.svg b/packages/twenty-agent-skills/assets/twenty-logo.svgsimilarity index 100%rename from packages/twenty-codex-plugin/assets/twenty-logo.svgrename to packages/twenty-agent-skills/assets/twenty-logo.svgdiff --git a/packages/twenty-agent-skills/package.json b/packages/twenty-agent-skills/package.jsonnew file mode 100644index 00000000000..c691766f2f6--- /dev/null+++ b/packages/twenty-agent-skills/package.json@@ -0,0 +1,30 @@+{+ "name": "twenty-agent-skills",+ "version": "0.1.0",+ "description": "Harness-agnostic Agent Skills for creating, developing, operating, and publishing Twenty apps.",+ "private": true,+ "type": "module",+ "license": "AGPL-3.0",+ "scripts": {+ "build": "node ./scripts/build.js",+ "validate": "node ./scripts/validate-source.js && node ./scripts/build.js && node ./scripts/validate-distribution.js",+ "test": "node --test ./scripts/__tests__/*.spec.js",+ "verify:install": "node ./scripts/verify-install.js",+ "setup:mcp": "bash ./scripts/setup-mcp.sh"+ },+ "files": [+ ".codex-plugin",+ ".mcp.json",+ "AGENTS.md",+ "README.md",+ "assets",+ "references",+ "skills",+ "scripts/setup-mcp.sh"+ ],+ "engines": {+ "node": "^24.5.0",+ "npm": "please-use-yarn",+ "yarn": ">=4.0.2"+ }+}diff --git a/packages/twenty-agent-skills/project.json b/packages/twenty-agent-skills/project.jsonnew file mode 100644index 00000000000..2b0d3b7974f--- /dev/null+++ b/packages/twenty-agent-skills/project.json@@ -0,0 +1,99 @@+{+ "name": "twenty-agent-skills",+ "$schema": "../../node_modules/nx/schemas/project-schema.json",+ "sourceRoot": "packages/twenty-agent-skills",+ "projectType": "library",+ "tags": ["scope:agent-skills"],+ "targets": {+ "build": {+ "executor": "nx:run-commands",+ "options": {+ "cwd": "{projectRoot}",+ "command": "node ./scripts/build.js"+ },+ "inputs": [+ "{projectRoot}/.codex-plugin/**/*",+ "{projectRoot}/.mcp.json",+ "{projectRoot}/*.md",+ "{projectRoot}/assets/**/*",+ "{projectRoot}/package.json",+ "{projectRoot}/references/**/*",+ "{projectRoot}/scripts/**/*",+ "{projectRoot}/skills/**/*",+ "{projectRoot}/templates/**/*"+ ],+ "outputs": ["{projectRoot}/dist"]+ },+ "validate": {+ "executor": "nx:run-commands",+ "cache": true,+ "options": {+ "cwd": "{projectRoot}",+ "command": "node ./scripts/validate-source.js && node ./scripts/build.js && node ./scripts/validate-distribution.js"+ },+ "inputs": [+ "{projectRoot}/.codex-plugin/**/*",+ "{projectRoot}/.mcp.json",+ "{projectRoot}/*.md",+ "{projectRoot}/assets/**/*",+ "{projectRoot}/package.json",+ "{projectRoot}/references/**/*",+ "{projectRoot}/scripts/**/*",+ "{projectRoot}/skills/**/*",+ "{projectRoot}/templates/**/*",+ "{projectRoot}/.gitignore",+ "{workspaceRoot}/.agents/plugins/marketplace.json"+ ],+ "outputs": ["{projectRoot}/dist"]+ },+ "test": {+ "executor": "nx:run-commands",+ "cache": true,+ "options": {+ "cwd": "{projectRoot}",+ "command": "node --test ./scripts/__tests__/*.spec.js"+ },+ "inputs": [+ "{projectRoot}/.codex-plugin/**/*",+ "{projectRoot}/.mcp.json",+ "{projectRoot}/*.md",+ "{projectRoot}/assets/**/*",+ "{projectRoot}/package.json",+ "{projectRoot}/references/**/*",+ "{projectRoot}/scripts/**/*",+ "{projectRoot}/skills/**/*",+ "{projectRoot}/templates/**/*",+ "{projectRoot}/.gitignore",+ "{workspaceRoot}/.agents/plugins/marketplace.json"+ ]+ },+ "verify:install": {+ "executor": "nx:run-commands",+ "options": {+ "cwd": "{projectRoot}",+ "command": "node ./scripts/verify-install.js"+ }+ },+ "fmt": {+ "executor": "nx:run-commands",+ "cache": true,+ "options": {+ "cwd": "{projectRoot}",+ "command": "prettier . --check --cache --cache-location ../../.cache/prettier/{projectRoot} --cache-strategy metadata"+ },+ "configurations": {+ "ci": {},+ "fix": {+ "command": "prettier . --write --cache --cache-location ../../.cache/prettier/{projectRoot} --cache-strategy metadata"+ }+ }+ },+ "setup:mcp": {+ "executor": "nx:run-commands",+ "options": {+ "cwd": "{projectRoot}",+ "command": "bash ./scripts/setup-mcp.sh"+ }+ }+ }+}diff --git a/packages/twenty-codex-plugin/references/concepts/how-apps-work.md b/packages/twenty-agent-skills/references/concepts/how-apps-work.mdsimilarity index 98%rename from packages/twenty-codex-plugin/references/concepts/how-apps-work.mdrename to packages/twenty-agent-skills/references/concepts/how-apps-work.mdindex 367deb14748..0f6ec75ec4f 100644--- a/packages/twenty-codex-plugin/references/concepts/how-apps-work.md+++ b/packages/twenty-agent-skills/references/concepts/how-apps-work.md@@ -66,7 +66,7 @@ Publishing is separate from the development loop. It is used to share an app wit- `yarn twenty app:publish` publishes to npm for the public marketplace.- `yarn twenty app:publish --private --remote <name>` publishes privately to a specific Twenty instance's registry.-Each publish requires a strictly higher semver version in `package.json`. See the `publish-app` skill and `prepare-for-app-store.md` for marketplace metadata and listing guidance.+Each publish requires a strictly higher semver version in `package.json`. See the `publish-app` skill for marketplace metadata and listing guidance.## Front Component Renderingdiff --git a/packages/twenty-agent-skills/references/concepts/operating-rules.md b/packages/twenty-agent-skills/references/concepts/operating-rules.mdnew file mode 100644index 00000000000..2f930c98a05--- /dev/null+++ b/packages/twenty-agent-skills/references/concepts/operating-rules.md@@ -0,0 +1,17 @@+# Operating Rules++These rules apply to every Twenty app task, in every skill and every agent harness. They exist because they have failed before.++This file is the single source of truth for the cross-skill rules. Harness-specific entry points link here instead of restating them, so the rules cannot drift between distributions.++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 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.++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. **Any Twenty instance is a valid target.** The user supplies the workspace or instance URL: managed cloud, self-hosted on a custom HTTPS domain, or localhost over HTTP. Never assume or require a `twenty.com` workspace.++6. **Workspace URLs and credentials stay user-local.** Never bundle workspace-specific MCP URLs in shared or committed files. Bearer tokens, API keys, and OAuth secrets belong in the user's private client config; `TWENTY_DEPLOY_API_KEY` and similar live in CI secret stores, never committed in source.diff --git a/packages/twenty-codex-plugin/references/design/front-component-ui.md b/packages/twenty-agent-skills/references/design/front-component-ui.mdsimilarity index 99%rename from packages/twenty-codex-plugin/references/design/front-component-ui.mdrename to packages/twenty-agent-skills/references/design/front-component-ui.mdindex c427f494158..a2bcdbc8d98 100644--- a/packages/twenty-codex-plugin/references/design/front-component-ui.md+++ b/packages/twenty-agent-skills/references/design/front-component-ui.md@@ -31,7 +31,7 @@ Prefer Twenty UI primitives for CRM-native front component UI:- Use `Tag`, `Status`, `Chip`, `Label`, and `Avatar` for metadata, state, people, and small summaries.- Use `themeCssVariables` for spacing, colors, border radius, typography, borders, icon sizing, shadows, and backgrounds.-Use local inline styles for layout containers and custom data displays, but keep them aligned with Twenty tokens. Use `front-components.md` for exact imports and runtime rules.+Use local inline styles for layout containers and custom data displays, but keep them aligned with Twenty tokens. Use `../develop-app/front-components.md` for exact imports and runtime rules.Use Twenty UI icons before custom SVG. Use `themeCssVariables.icon.size.md` for default row and action icons, `themeCssVariables.icon.size.sm` for quiet chevrons, and `themeCssVariables.spacing[6]` for icon-only action targets.diff --git a/packages/twenty-codex-plugin/references/develop-app/app-structure.md b/packages/twenty-agent-skills/references/develop-app/app-structure.mdsimilarity index 100%rename from packages/twenty-codex-plugin/references/develop-app/app-structure.mdrename to packages/twenty-agent-skills/references/develop-app/app-structure.mddiff --git a/packages/twenty-codex-plugin/references/develop-app/data-model.md b/packages/twenty-agent-skills/references/develop-app/data-model.mdsimilarity index 100%rename from packages/twenty-codex-plugin/references/develop-app/data-model.mdrename to packages/twenty-agent-skills/references/develop-app/data-model.mddiff --git a/packages/twenty-codex-plugin/references/develop-app/front-components.md b/packages/twenty-agent-skills/references/develop-app/front-components.mdsimilarity index 100%rename from packages/twenty-codex-plugin/references/develop-app/front-components.mdrename to packages/twenty-agent-skills/references/develop-app/front-components.mddiff --git a/packages/twenty-codex-plugin/references/develop-app/layout.md b/packages/twenty-agent-skills/references/develop-app/layout.mdsimilarity index 100%rename from packages/twenty-codex-plugin/references/develop-app/layout.mdrename to packages/twenty-agent-skills/references/develop-app/layout.mddiff --git a/packages/twenty-codex-plugin/references/develop-app/logic.md b/packages/twenty-agent-skills/references/develop-app/logic.mdsimilarity index 100%rename from packages/twenty-codex-plugin/references/develop-app/logic.mdrename to packages/twenty-agent-skills/references/develop-app/logic.mddiff --git a/packages/twenty-codex-plugin/references/develop-app/standalone-pages.md b/packages/twenty-agent-skills/references/develop-app/standalone-pages.mdsimilarity index 100%rename from packages/twenty-codex-plugin/references/develop-app/standalone-pages.mdrename to packages/twenty-agent-skills/references/develop-app/standalone-pages.mddiff --git a/packages/twenty-codex-plugin/references/develop-app/tests.md b/packages/twenty-agent-skills/references/develop-app/tests.mdsimilarity index 100%rename from packages/twenty-codex-plugin/references/develop-app/tests.mdrename to packages/twenty-agent-skills/references/develop-app/tests.mddiff --git a/packages/twenty-codex-plugin/references/develop-app/workflows.md b/packages/twenty-agent-skills/references/develop-app/workflows.mdsimilarity index 100%rename from packages/twenty-codex-plugin/references/develop-app/workflows.mdrename to packages/twenty-agent-skills/references/develop-app/workflows.mddiff --git a/packages/twenty-codex-plugin/references/manage-app/cli-and-sync.md b/packages/twenty-agent-skills/references/manage-app/cli-and-sync.mdsimilarity index 100%rename from packages/twenty-codex-plugin/references/manage-app/cli-and-sync.mdrename to packages/twenty-agent-skills/references/manage-app/cli-and-sync.mddiff --git a/packages/twenty-codex-plugin/references/publish-app/prepare-for-app-store.md b/packages/twenty-agent-skills/references/publish-app/prepare-for-app-store.mdsimilarity index 100%rename from packages/twenty-codex-plugin/references/publish-app/prepare-for-app-store.mdrename to packages/twenty-agent-skills/references/publish-app/prepare-for-app-store.mddiff --git a/packages/twenty-codex-plugin/references/use-twenty-mcp/result-formatting.md b/packages/twenty-agent-skills/references/use-twenty-mcp/result-formatting.mdsimilarity index 100%rename from packages/twenty-codex-plugin/references/use-twenty-mcp/result-formatting.mdrename to packages/twenty-agent-skills/references/use-twenty-mcp/result-formatting.mddiff --git a/packages/twenty-agent-skills/references/use-twenty-mcp/setup.md b/packages/twenty-agent-skills/references/use-twenty-mcp/setup.mdnew file mode 100644index 00000000000..63288ade780--- /dev/null+++ b/packages/twenty-agent-skills/references/use-twenty-mcp/setup.md@@ -0,0 +1,158 @@+# Set Up Twenty MCP++## Overview++Use this reference to configure a workspace-specific Twenty MCP endpoint. The skill must not assume a fixed workspace domain; collect the user's workspace URL first, normalize it to an MCP URL, then configure and authenticate the MCP client of the agent in use.++Self-hosted instances are first-class targets. Any Twenty workspace works: managed cloud, self-hosted on a custom domain, or a local instance over HTTP. Never require a `twenty.com` workspace.++## Required User Input++Ask for the workspace URL or host if it is missing. Do not invent or reuse a private default domain.++Accept any of these forms:++```text+myworkspace.twenty.com+myworkspace.customdomain.com+myworkspace.localhost:3001+https://myworkspace.twenty.com+https://myworkspace.customdomain.com/mcp+http://myworkspace.localhost:3001/mcp+```++Optional inputs:++- MCP server name. Default to a workspace-derived name in the form `twenty-<host-without-tld>`, for example `acme.example.com` becomes `twenty-acme-example`.+- Whether to force CLI OAuth login immediately. Default to no when the agent opens OAuth on its own after the MCP server is added. Only force login if the automatic OAuth window does not appear.++## URL Normalization++Normalize workspace input as follows:++- If the input already starts with `http://` or `https://`, preserve that scheme.+- If the input has no scheme and is `localhost`, `127.x.x.x`, `[::1]`, `*.localhost`, or `*.localhost:<port>`, use `http://`.+- If the input has no scheme and is any other host, use `https://`.+- Strip any trailing `/` before looking at the path, so `https://acme.example.com/` and `https://acme.example.com/mcp/` normalize the same as their unslashed forms.+- If the final URL does not end with `/mcp`, append `/mcp`.++Examples:++```text+myworkspace.twenty.com -> https://myworkspace.twenty.com/mcp name: twenty-myworkspace+acme.example.com -> https://acme.example.com/mcp name: twenty-acme-example+myworkspace.customdomain.com -> https://myworkspace.customdomain.com/mcp name: twenty-myworkspace-customdomain+myworkspace.localhost:3001 -> http://myworkspace.localhost:3001/mcp name: twenty-myworkspace-localhost-3001+https://acme.example.com/ -> https://acme.example.com/mcp name: twenty-acme-example+https://acme.example.com/mcp/ -> https://acme.example.com/mcp name: twenty-acme-example+```++A trailing slash that survives normalization produces `//mcp` or `/mcp//mcp`, neither of which is the registered endpoint.++## Setup Per Agent++The Twenty MCP server uses streamable HTTP transport with OAuth authentication. Configure it with the agent the user is actually running.++### Codex++```bash+codex mcp add twenty-myworkspace --url https://myworkspace.twenty.com/mcp+codex mcp login twenty-myworkspace+```++For a local instance:++```bash+codex mcp add twenty-local --url http://myworkspace.localhost:3001/mcp+codex mcp login twenty-local+```++OAuth guards specific to this client:++- Do not pass `--login` to `codex mcp add`. It is deprecated.+- Codex can open OAuth on its own when it sees the new MCP server. Run `codex mcp login <server-name>` only if that window does not appear.+- Do not manually run `open <authorization-url>` for an OAuth URL printed by `codex mcp add` unless the user confirms no browser tab opened. Opening the same authorization URL twice creates two callback tabs with the same `state` and different one-time `code` values.++The Twenty marketplace plugin for this client bundles a `setup-mcp.sh` helper that automates URL normalization, server naming, and this add-then-login sequence.++### Claude Code++```bash+claude mcp add --transport http twenty-myworkspace https://myworkspace.twenty.com/mcp+```++For a local instance:++```bash+claude mcp add --transport http twenty-local http://myworkspace.localhost:3001/mcp+```++Claude Code prompts for OAuth when the server is first used. `/mcp` inside a session shows connection and authentication status, and re-runs the OAuth flow on demand.++### Cursor++Add the server to `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` for every project:++```json+{+ "mcpServers": {+ "twenty-myworkspace": {+ "url": "https://myworkspace.twenty.com/mcp"+ }+ }+}+```++Cursor opens the OAuth flow when the server is enabled in its MCP settings.++### Other MCP Clients++Any client that supports streamable HTTP MCP servers with OAuth works. Configure a server entry pointing at the normalized MCP URL:++```json+{+ "mcpServers": {+ "twenty-myworkspace": {+ "url": "https://myworkspace.twenty.com/mcp"+ }+ }+}+```++If the client cannot do OAuth, configure bearer headers in the user's private MCP client config only, never in shared or committed files.++## Validation++After setup, verify the server is available with the client's own inspection command (`codex mcp get <server-name>`, `claude mcp list`, or the equivalent), or by listing available tools in a fresh session.++When connected, use the Twenty MCP discovery flow:++```text+learn_tools -> execute_tool+```++## Troubleshooting++### Debugging Workflow++Use this workflow when the user reports missing tools, unexpected workspace data, authentication failures, or suspects the agent queried the wrong Twenty workspace.++1. Identify the intended workspace URL or host from the user's request, using Required User Input when it is missing.+2. Normalize the intended workspace to its MCP URL with the URL Normalization rules above.+3. Inspect the configured Twenty MCP servers and compare their URLs to the intended normalized URL (`codex mcp list`, `claude mcp list`, or the client's MCP config file).+4. If no configured server points at the intended MCP URL, configure one with a workspace-specific name using the per-agent setup above.+5. If the server exists but authentication fails, or MCP startup reports `Auth required`, run the client's OAuth login for that exact server.+6. If the configured server is correct and authenticated but its tools are not visible in the current session, explain that the session may have loaded tools before the server was added or authenticated. Ask the user to reload the agent or start a new session so it picks up the updated MCP config.+7. Before querying workspace data, confirm the callable Twenty MCP namespace or tool name corresponds to the intended server. If only a different Twenty server is callable, do not use it as a fallback unless the user explicitly asks.+8. When reporting results, state which workspace URL or MCP server was used if there was any ambiguity.++### Common Failure Modes++- If OAuth fails for a self-hosted workspace, check that `SERVER_URL` matches the public workspace origin. OAuth metadata and MCP URLs derive from that value.+- If a local workspace fails over HTTPS, use `http://` explicitly per the localhost normalization rule.+- If the server name already exists, replace that entry with the new URL, or pick a different name to keep several workspaces side by side.++### Safety Rules++- Do not put API keys in skill files. Prefer OAuth login. If an MCP client does not support OAuth, configure bearer headers only in the user's private MCP client config.+- Do not inspect or manually extract OAuth tokens as a workaround.diff --git a/packages/twenty-agent-skills/scripts/__tests__/distribution-validation.spec.js b/packages/twenty-agent-skills/scripts/__tests__/distribution-validation.spec.jsnew file mode 100644index 00000000000..848052ac745--- /dev/null+++ b/packages/twenty-agent-skills/scripts/__tests__/distribution-validation.spec.js@@ -0,0 +1,372 @@+import assert from 'node:assert/strict';+import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import { afterEach, beforeEach, describe, it } from 'node:test';++import { CANONICAL_SKILL_NAMES } from '../lib.js';+import {+ assertSkillFrontmatter,+ assertSelfContainedReferences,+ assertPortability,+ assertSharedReferenceConsistency,+ assertOperatingRulesShipped,+ assertNoDanglingDocMentions,+ validatePortableSkills,+} from '../validate-distribution.js';+import { writeFixtureFile } from './fixtures.js';++const writeValidSkill = (skillsRoot, skillName) => {+ writeFixtureFile(+ skillsRoot,+ `${skillName}/SKILL.md`,+ `---\nname: ${skillName}\ndescription: Demo skill.\n---\n\n# When To Use\n\nRead \`references/concepts/basics.md\` and \`references/concepts/operating-rules.md\`.\n`,+ );+ writeFixtureFile(+ skillsRoot,+ `${skillName}/references/concepts/basics.md`,+ 'Basics.\n',+ );+ writeFixtureFile(+ skillsRoot,+ `${skillName}/references/concepts/operating-rules.md`,+ 'Rules.\n',+ );+};++describe('validatePortableSkills', () => {+ let skillsRoot;+ let failures;+ const fail = (message) => failures.push(message);++ beforeEach(() => {+ skillsRoot = fs.mkdtempSync(+ path.join(os.tmpdir(), 'agent-skills-validate-'),+ );+ failures = [];+ });++ afterEach(() => {+ fs.rmSync(skillsRoot, { recursive: true, force: true });+ });++ it('should pass for a complete, self-contained skill set', () => {+ for (const skillName of CANONICAL_SKILL_NAMES) {+ writeValidSkill(skillsRoot, skillName);+ }++ writeFixtureFile(+ skillsRoot,+ 'create-app/SKILL.md',+ '---\nname: create-app\ndescription: Demo skill.\n---\n\n# When To Use\n\nWorks against self-hosted instances. Read `references/concepts/operating-rules.md`.\n',+ );++ validatePortableSkills(skillsRoot, fail);++ assert.deepEqual(failures, []);+ });++ it('should fail when a portable skill is missing or unexpected', () => {+ writeValidSkill(skillsRoot, 'create-app');+ writeValidSkill(skillsRoot, 'not-a-twenty-skill');++ validatePortableSkills(skillsRoot, fail);++ assert.ok(failures.includes('portable skill is missing: develop-app'));+ assert.ok(+ failures.includes('unexpected skill directory: not-a-twenty-skill'),+ );+ });++ it('should fail when frontmatter name does not match the directory', () => {+ writeFixtureFile(+ skillsRoot,+ 'create-app/SKILL.md',+ '---\nname: other-name\ndescription: Demo.\n---\n\n# When To Use\n\nText.\n',+ );++ assertSkillFrontmatter({ skillsRoot, skillName: 'create-app', fail });++ assert.ok(+ failures.includes(+ 'create-app/SKILL.md frontmatter name must match its directory',+ ),+ );+ });++ it('should fail when frontmatter includes extra fields or misses the trigger section', () => {+ writeFixtureFile(+ skillsRoot,+ 'create-app/SKILL.md',+ '---\nname: create-app\ndescription: Demo.\nlicense: MIT\n---\n\nNo trigger section.\n',+ );++ assertSkillFrontmatter({ skillsRoot, skillName: 'create-app', fail });++ assert.ok(+ failures.includes(+ 'create-app/SKILL.md frontmatter should only include name and description',+ ),+ );+ assert.ok(+ failures.includes(+ 'create-app/SKILL.md must include a "When To Use" section',+ ),+ );+ });++ it('should fail when a reference escapes the skill directory', () => {+ writeFixtureFile(+ skillsRoot,+ 'create-app/SKILL.md',+ '---\nname: create-app\ndescription: Demo.\n---\n\n# When To Use\n\nRead `../../references/concepts/basics.md`.\n',+ );++ assertSelfContainedReferences({+ skillsRoot,+ skillName: 'create-app',+ fail,+ });++ assert.ok(+ failures.some((failure) =>+ failure.includes('references a path outside its skill directory'),+ ),+ );+ });++ it('should fail when a referenced file is missing after installation', () => {+ writeFixtureFile(+ skillsRoot,+ 'create-app/SKILL.md',+ '---\nname: create-app\ndescription: Demo.\n---\n\n# When To Use\n\nRead `references/concepts/missing.md`.\n',+ );++ assertSelfContainedReferences({+ skillsRoot,+ skillName: 'create-app',+ fail,+ });++ assert.ok(+ failures.includes(+ 'create-app/SKILL.md references a missing file: references/concepts/missing.md',+ ),+ );+ });++ it('should fail when a skill ships an unexpected executable file', () => {+ writeValidSkill(skillsRoot, 'create-app');+ writeFixtureFile(skillsRoot, 'create-app/script.js', 'console.log(1);\n');++ assertSelfContainedReferences({+ skillsRoot,+ skillName: 'create-app',+ fail,+ });++ assert.ok(+ failures.includes(+ 'portable skills may only contain markdown and agents/openai.yaml: create-app/script.js',+ ),+ );+ });++ it('should fail when content depends on the codex plugin wrapper', () => {+ writeFixtureFile(+ skillsRoot,+ 'create-app/SKILL.md',+ '---\nname: create-app\ndescription: Demo.\n---\n\n# When To Use\n\nRun `bash packages/twenty-codex-plugin/scripts/setup-mcp.sh`.\n',+ );++ assertPortability({ skillsRoot, skillName: 'create-app', fail });++ assert.ok(+ failures.includes(+ 'create-app/SKILL.md must not depend on non-portable content: packages/twenty-codex-plugin',+ ),+ );+ });++ it('should fail on non-placeholder URLs', () => {+ writeFixtureFile(+ skillsRoot,+ 'create-app/SKILL.md',+ '---\nname: create-app\ndescription: Demo.\n---\n\n# When To Use\n\nVisit https://some-random-host.dev/docs.\n',+ );++ assertPortability({ skillsRoot, skillName: 'create-app', fail });++ assert.ok(+ failures.includes(+ 'non-placeholder URL found in create-app/SKILL.md: https://some-random-host.dev',+ ),+ );+ });++ it('should fail when a shared reference diverges between skills', () => {+ writeValidSkill(skillsRoot, 'create-app');+ writeValidSkill(skillsRoot, 'develop-app');+ writeFixtureFile(+ skillsRoot,+ 'develop-app/references/concepts/basics.md',+ 'Diverged basics.\n',+ );++ assertSharedReferenceConsistency(+ skillsRoot,+ ['create-app', 'develop-app'],+ fail,+ );++ assert.deepEqual(failures, [+ 'shared reference diverges between create-app and develop-app: references/concepts/basics.md',+ ]);+ });+});++describe('assertOperatingRulesShipped', () => {+ let skillsRoot;+ let failures;+ const fail = (message) => failures.push(message);++ beforeEach(() => {+ skillsRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-skills-rules-'));+ failures = [];+ });++ afterEach(() => {+ fs.rmSync(skillsRoot, { recursive: true, force: true });+ });++ it('should fail when an app skill does not ship the operating rules', () => {+ for (const skillName of CANONICAL_SKILL_NAMES) {+ writeValidSkill(skillsRoot, skillName);+ }++ fs.rmSync(+ path.join(+ skillsRoot,+ 'manage-app/references/concepts/operating-rules.md',+ ),+ );++ assertOperatingRulesShipped(skillsRoot, fail);++ assert.ok(+ failures.some((failure) =>+ failure.startsWith('manage-app does not ship'),+ ),+ `expected a missing operating-rules failure, got: ${failures.join('; ')}`,+ );+ });++ it('should fail when an app skill does not link to the operating rules', () => {+ for (const skillName of CANONICAL_SKILL_NAMES) {+ writeValidSkill(skillsRoot, skillName);+ }++ writeFixtureFile(+ skillsRoot,+ 'publish-app/SKILL.md',+ '---\nname: publish-app\ndescription: Demo skill.\n---\n\n# When To Use\n\nNo rules link here.\n',+ );++ assertOperatingRulesShipped(skillsRoot, fail);++ assert.ok(+ failures.some((failure) =>+ failure.includes('publish-app/SKILL.md must link'),+ ),+ `expected a missing link failure, got: ${failures.join('; ')}`,+ );+ });+});++describe('assertNoDanglingDocMentions', () => {+ let skillsRoot;+ let failures;+ const fail = (message) => failures.push(message);++ beforeEach(() => {+ skillsRoot = fs.mkdtempSync(+ path.join(os.tmpdir(), 'agent-skills-mentions-'),+ );+ failures = [];+ });++ afterEach(() => {+ fs.rmSync(skillsRoot, { recursive: true, force: true });+ });++ it('should fail when a skill mentions a doc another skill ships but it does not', () => {+ writeValidSkill(skillsRoot, 'create-app');+ writeValidSkill(skillsRoot, 'develop-app');+ writeFixtureFile(+ skillsRoot,+ 'develop-app/references/develop-app/front-components.md',+ 'Front components.\n',+ );+ writeFixtureFile(+ skillsRoot,+ 'create-app/references/design/front-component-ui.md',+ 'Use `front-components.md` for exact imports.\n',+ );++ assertNoDanglingDocMentions(+ skillsRoot,+ ['create-app', 'develop-app'],+ fail,+ );++ assert.ok(+ failures.some(+ (failure) =>+ failure.includes('front-components.md') &&+ failure.includes('create-app does not ship'),+ ),+ `expected a dangling mention failure, got: ${failures.join('; ')}`,+ );+ });++ it('should ignore filenames that belong to the user rather than the collection', () => {+ writeValidSkill(skillsRoot, 'publish-app');+ writeFixtureFile(+ skillsRoot,+ 'publish-app/references/concepts/basics.md',+ 'Inspect `README.md` and `package.json` in the app.\n',+ );++ assertNoDanglingDocMentions(skillsRoot, ['publish-app'], fail);++ assert.deepEqual(failures, []);+ });+});++describe('verify-install argument handling', () => {+ let installRoot;++ beforeEach(() => {+ installRoot = fs.mkdtempSync(+ path.join(os.tmpdir(), 'agent-skills-install-'),+ );+ });++ afterEach(() => {+ fs.rmSync(installRoot, { recursive: true, force: true });+ });++ it('should not report escaping references when given a relative install root', () => {+ const failures = [];+ const fail = (message) => failures.push(message);++ writeValidSkill(installRoot, 'create-app');+ assertSelfContainedReferences({+ skillsRoot: path.resolve(installRoot),+ skillName: 'create-app',+ fail,+ });++ assert.deepEqual(failures, []);+ });+});diff --git a/packages/twenty-agent-skills/scripts/__tests__/fixtures.js b/packages/twenty-agent-skills/scripts/__tests__/fixtures.jsnew file mode 100644index 00000000000..518b219047a--- /dev/null+++ b/packages/twenty-agent-skills/scripts/__tests__/fixtures.js@@ -0,0 +1,11 @@+import fs from 'node:fs';+import path from 'node:path';++const writeFixtureFile = (root, relativePath, contents) => {+ const absolutePath = path.join(root, relativePath);++ fs.mkdirSync(path.dirname(absolutePath), { recursive: true });+ fs.writeFileSync(absolutePath, contents);+};++export { writeFixtureFile };diff --git a/packages/twenty-agent-skills/scripts/__tests__/lib.spec.js b/packages/twenty-agent-skills/scripts/__tests__/lib.spec.jsnew file mode 100644index 00000000000..c7dbadca52e--- /dev/null+++ b/packages/twenty-agent-skills/scripts/__tests__/lib.spec.js@@ -0,0 +1,355 @@+import assert from 'node:assert/strict';+import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import { afterEach, beforeEach, describe, it } from 'node:test';++import {+ rewriteSkillReferenceLinks,+ collectSkillSeedReferences,+ resolveReferenceClosure,+ buildPortableSkills,+ buildDistribution,+ CANONICAL_SKILL_NAMES,+ listFiles,+} from '../lib.js';+import { writeFixtureFile } from './fixtures.js';++describe('rewriteSkillReferenceLinks', () => {+ it('should rewrite plugin-relative reference links to skill-relative links', () => {+ const rewritten = rewriteSkillReferenceLinks(+ 'Read `../../references/concepts/how-apps-work.md` and `../../references/develop-app/tests.md`.',+ );++ assert.equal(+ rewritten,+ 'Read `references/concepts/how-apps-work.md` and `references/develop-app/tests.md`.',+ );+ });++ it('should leave skill-relative links untouched', () => {+ const contents = 'Read `references/concepts/how-apps-work.md`.';++ assert.equal(rewriteSkillReferenceLinks(contents), contents);+ });+});++describe('collectSkillSeedReferences', () => {+ it('should collect plugin-relative and skill-relative reference mentions', () => {+ const seeds = collectSkillSeedReferences(+ 'Read `../../references/concepts/how-apps-work.md` then `references/design/front-component-ui.md`.',+ );++ assert.deepEqual([...seeds].sort(), [+ 'concepts/how-apps-work.md',+ 'design/front-component-ui.md',+ ]);+ });+});++describe('resolveReferenceClosure', () => {+ let fixtureRoot;++ beforeEach(() => {+ fixtureRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-skills-lib-'));+ });++ afterEach(() => {+ fs.rmSync(fixtureRoot, { recursive: true, force: true });+ });++ it('should follow sibling-scope and same-directory reference mentions transitively', () => {+ writeFixtureFile(fixtureRoot, 'references/a/one.md', 'See `../b/two.md`.');+ writeFixtureFile(fixtureRoot, 'references/b/two.md', 'See `three.md`.');+ writeFixtureFile(fixtureRoot, 'references/b/three.md', 'Terminal doc.');++ const closure = resolveReferenceClosure(+ path.join(fixtureRoot, 'references'),+ new Set(['a/one.md']),+ );++ assert.deepEqual([...closure].sort(), [+ 'a/one.md',+ 'b/three.md',+ 'b/two.md',+ ]);+ });++ it('should ignore backtick tokens that only look like markdown files', () => {+ writeFixtureFile(+ fixtureRoot,+ 'references/design/ui.md',+ 'Use `themeCssVariables.font.size.md` for medium font size.',+ );++ const closure = resolveReferenceClosure(+ path.join(fixtureRoot, 'references'),+ new Set(['design/ui.md']),+ );++ assert.deepEqual([...closure], ['design/ui.md']);+ });++ it('should throw when a referenced doc does not exist', () => {+ writeFixtureFile(+ fixtureRoot,+ 'references/a/one.md',+ 'See `../b/missing.md`.',+ );++ assert.throws(+ () =>+ resolveReferenceClosure(+ path.join(fixtureRoot, 'references'),+ new Set(['a/one.md']),+ ),+ /referenced doc does not exist: references\/b\/missing\.md/,+ );+ });+});++describe('buildPortableSkills', () => {+ let sourceRoot;+ let outputRoot;++ beforeEach(() => {+ sourceRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-skills-source-'));+ outputRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-skills-output-'));+ writeFixtureFile(+ sourceRoot,+ 'skills/demo-skill/SKILL.md',+ '---\nname: demo-skill\ndescription: Demo.\n---\n\nRead `../../references/concepts/basics.md`.\n',+ );+ writeFixtureFile(+ sourceRoot,+ 'skills/demo-skill/agents/openai.yaml',+ 'interface: {}\n',+ );+ writeFixtureFile(+ sourceRoot,+ 'references/concepts/basics.md',+ 'See `../deep/detail.md`.',+ );+ writeFixtureFile(sourceRoot, 'references/deep/detail.md', 'Terminal doc.');+ });++ afterEach(() => {+ fs.rmSync(sourceRoot, { recursive: true, force: true });+ fs.rmSync(outputRoot, { recursive: true, force: true });+ });++ it('should emit a self-contained skill including optional Codex display metadata', () => {+ buildPortableSkills({ sourceRoot, outputRoot, skillNames: ['demo-skill'] });++ const skillMarkdown = fs.readFileSync(+ path.join(outputRoot, 'demo-skill', 'SKILL.md'),+ 'utf8',+ );++ assert.match(skillMarkdown, /`references\/concepts\/basics\.md`/);+ assert.ok(+ fs.existsSync(+ path.join(outputRoot, 'demo-skill', 'references/concepts/basics.md'),+ ),+ );+ assert.ok(+ fs.existsSync(+ path.join(outputRoot, 'demo-skill', 'references/deep/detail.md'),+ ),+ );+ assert.equal(+ fs.readFileSync(+ path.join(outputRoot, 'demo-skill', 'agents/openai.yaml'),+ 'utf8',+ ),+ 'interface: {}\n',+ );+ });++ it('should remove stale files from a previous build', () => {+ writeFixtureFile(outputRoot, 'stale-skill/SKILL.md', 'stale');++ buildPortableSkills({ sourceRoot, outputRoot, skillNames: ['demo-skill'] });++ assert.ok(!fs.existsSync(path.join(outputRoot, 'stale-skill')));+ });++ it('should throw when a canonical skill is missing', () => {+ assert.throws(+ () =>+ buildPortableSkills({+ sourceRoot,+ outputRoot,+ skillNames: ['absent-skill'],+ }),+ /canonical skill is missing: skills\/absent-skill\/SKILL\.md/,+ );+ });+});++describe('resolveReferenceClosure cross-scope mentions', () => {+ let referencesRoot;++ beforeEach(() => {+ referencesRoot = fs.mkdtempSync(+ path.join(os.tmpdir(), 'agent-skills-closure-'),+ );+ });++ afterEach(() => {+ fs.rmSync(referencesRoot, { recursive: true, force: true });+ });++ it('should throw when a bare mention names a doc that lives in another scope', () => {+ writeFixtureFile(+ referencesRoot,+ 'design/front-component-ui.md',+ 'Use `front-components.md` for exact imports.\n',+ );+ writeFixtureFile(+ referencesRoot,+ 'develop-app/front-components.md',+ 'Front components.\n',+ );++ assert.throws(+ () =>+ resolveReferenceClosure(referencesRoot, [+ 'design/front-component-ui.md',+ ]),+ /lives at references\/develop-app\/front-components\.md/,+ );+ });++ it('should still ignore bare mentions that name no reference doc', () => {+ writeFixtureFile(+ referencesRoot,+ 'publish-app/prepare-for-app-store.md',+ 'Write the app `README.md` and set `themeCssVariables.font.size.md`.\n',+ );++ const closure = resolveReferenceClosure(referencesRoot, [+ 'publish-app/prepare-for-app-store.md',+ ]);++ assert.deepEqual([...closure], ['publish-app/prepare-for-app-store.md']);+ });+});++describe('buildDistribution', () => {+ let fixtureRoot;++ beforeEach(() => {+ fixtureRoot = fs.mkdtempSync(+ path.join(os.tmpdir(), 'twenty-distribution-'),+ );+ });++ afterEach(() => {+ fs.rmSync(fixtureRoot, { recursive: true, force: true });+ });++ it('builds one standalone plugin and skill collection without modifying source', () => {+ const sourceRoot = path.join(fixtureRoot, 'source');+ const outputRoot = path.join(fixtureRoot, 'dist');+ const files = [+ '.codex-plugin',+ '.mcp.json',+ 'assets',+ 'skills',+ 'scripts/setup-mcp.sh',+ ];++ writeFixtureFile(+ sourceRoot,+ 'package.json',+ JSON.stringify({+ name: 'twenty-agent-skills',+ version: '0.1.0',+ license: 'AGPL-3.0',+ files,+ scripts: { build: 'node scripts/build.js' },+ }),+ );+ writeFixtureFile(+ sourceRoot,+ '.codex-plugin/plugin.json',+ '{"name":"twenty","skills":"./skills/"}',+ );+ writeFixtureFile(sourceRoot, '.mcp.json', '{"mcpServers":{}}');+ writeFixtureFile(sourceRoot, 'assets/logo.png', 'binary-asset');+ writeFixtureFile(sourceRoot, 'scripts/setup-mcp.sh', '#!/bin/sh\nexit 0\n');+ fs.chmodSync(path.join(sourceRoot, 'scripts/setup-mcp.sh'), 0o755);+ writeFixtureFile(sourceRoot, 'scripts/build.js', 'build-only');+ writeFixtureFile(+ sourceRoot,+ 'references/concepts/basics.md',+ 'Shared concept.',+ );++ for (const skillName of CANONICAL_SKILL_NAMES) {+ writeFixtureFile(+ sourceRoot,+ `skills/${skillName}/SKILL.md`,+ 'Read `../../references/concepts/basics.md`.',+ );+ writeFixtureFile(+ sourceRoot,+ `skills/${skillName}/agents/openai.yaml`,+ 'interface: {}\n',+ );+ }++ const snapshot = (root) =>+ listFiles(root).map((file) => [+ path.relative(root, file),+ fs.readFileSync(file),+ ]);+ const sourceBefore = snapshot(sourceRoot);+ buildDistribution({ sourceRoot, outputRoot });+ const distributionBefore = snapshot(outputRoot);+ writeFixtureFile(outputRoot, 'removed-skill/SKILL.md', 'stale');+ buildDistribution({ sourceRoot, outputRoot });++ assert.deepEqual(snapshot(sourceRoot), sourceBefore);+ assert.deepEqual(snapshot(outputRoot), distributionBefore);+ assert.ok(+ fs.existsSync(path.join(outputRoot, '.codex-plugin/plugin.json')),+ );+ assert.ok(fs.existsSync(path.join(outputRoot, '.mcp.json')));+ assert.ok(fs.existsSync(path.join(outputRoot, 'assets/logo.png')));+ assert.ok(!fs.existsSync(path.join(outputRoot, 'scripts/build.js')));+ assert.equal(+ fs.statSync(path.join(outputRoot, 'scripts/setup-mcp.sh')).mode & 0o777,+ 0o755,+ );+ assert.equal(+ JSON.parse(fs.readFileSync(path.join(outputRoot, 'package.json'), 'utf8'))+ .scripts,+ undefined,+ );++ fs.rmSync(sourceRoot, { recursive: true });+ for (const skillName of CANONICAL_SKILL_NAMES) {+ const skillRoot = path.join(outputRoot, 'skills', skillName);+ assert.equal(+ fs.readFileSync(path.join(skillRoot, 'SKILL.md'), 'utf8'),+ 'Read `references/concepts/basics.md`.',+ );+ assert.equal(+ fs.readFileSync(+ path.join(skillRoot, 'references/concepts/basics.md'),+ 'utf8',+ ),+ 'Shared concept.',+ );+ assert.equal(+ fs.readFileSync(path.join(skillRoot, 'agents/openai.yaml'), 'utf8'),+ 'interface: {}\n',+ );+ assert.ok(+ listFiles(skillRoot).every((file) => fs.lstatSync(file).isFile()),+ );+ }+ });+});diff --git a/packages/twenty-codex-plugin/scripts/__tests__/validate.spec.js b/packages/twenty-agent-skills/scripts/__tests__/source-validation.spec.jssimilarity index 68%rename from packages/twenty-codex-plugin/scripts/__tests__/validate.spec.jsrename to packages/twenty-agent-skills/scripts/__tests__/source-validation.spec.jsindex decda48d627..17747e86c11 100644--- a/packages/twenty-codex-plugin/scripts/__tests__/validate.spec.js+++ b/packages/twenty-agent-skills/scripts/__tests__/source-validation.spec.js@@ -1,21 +1,26 @@-const { test } = require('node:test');-const assert = require('node:assert');-const fs = require('node:fs');-const path = require('node:path');--const PLUGIN_ROOT = path.resolve(__dirname, '..', '..');+import { test } from 'node:test';+import assert from 'node:assert';+import fs from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++import * as metadata from '../validators/metadata.js';+import * as assets from '../validators/assets.js';+import * as skills from '../validators/skills.js';+import * as references from '../validators/references.js';+import * as crossDocContracts from '../validators/cross-doc-contracts.js';+import * as setupHelper from '../validators/setup-helper.js';++const PLUGIN_ROOT = path.resolve(+ path.dirname(fileURLToPath(import.meta.url)),+ '..',+ '..',+);const PLUGIN_JSON_PATH = path.join(PLUGIN_ROOT, '.codex-plugin', 'plugin.json');const PACKAGE_JSON_PATH = path.join(PLUGIN_ROOT, 'package.json');const MCP_JSON_PATH = path.join(PLUGIN_ROOT, '.mcp.json');const MARKETPLACE_TEMPLATE_PATH = path.join(PLUGIN_ROOT, 'templates', 'marketplace.example.json');-const metadata = require('../validators/metadata');-const assets = require('../validators/assets');-const skills = require('../validators/skills');-const references = require('../validators/references');-const crossDocContracts = require('../validators/cross-doc-contracts');-const setupHelper = require('../validators/setup-helper');-const collectFailures = (assertion) => {const failures = [];assertion((message) => failures.push(message));@@ -265,6 +270,22 @@ test('assertNoBundledMcpConfig catches a bearer token', () => {});});+test('source scans ignore generated distribution files', () => {+ const distributionRoot = path.join(PLUGIN_ROOT, 'dist');+ fs.mkdirSync(distributionRoot, { recursive: true });+ const fixtureRoot = fs.mkdtempSync(path.join(distributionRoot, 'source-validation-'));++ try {+ fs.writeFileSync(path.join(fixtureRoot, '.mcp.json'), '{}');+ fs.writeFileSync(path.join(fixtureRoot, 'SKILL.md'), 'name: create-an-app\n');++ assert.deepStrictEqual(collectFailures(metadata.assertNoBundledMcpConfig), []);+ assert.deepStrictEqual(collectFailures(skills.assertNoLegacySkillReferences), []);+ } finally {+ fs.rmSync(fixtureRoot, { recursive: true, force: true });+ }+});+test('assertInterfaceFields catches invalid brandColor', () => {withJsonMutation(PLUGIN_JSON_PATH, (j) => { j.interface.brandColor = 'red'; }, () => {const failures = collectFailures(metadata.assertInterfaceFields);@@ -316,12 +337,46 @@ test('assertAssets catches a non-PNG logo', () => {});});-test('assertMarketplaceTemplate catches version drift', () => {- withJsonMutation(MARKETPLACE_TEMPLATE_PATH, (t) => {- t.plugins[0].version = '0.0.0';+test('assertMarketplaceTemplate requires marketplace identity', () => {+ withJsonMutation(MARKETPLACE_TEMPLATE_PATH, (template) => {+ delete template.name;+ delete template.interface;+ }, () => {+ const failures = collectFailures(metadata.assertMarketplaceTemplate);+ assert.ok(failures.some((failure) => failure.includes('name must be a non-empty string')));+ assert.ok(failures.some((failure) => failure.includes('interface.displayName must be a non-empty string')));+ });+});++test('assertMarketplaceTemplate catches the legacy source descriptor', () => {+ withJsonMutation(MARKETPLACE_TEMPLATE_PATH, (template) => {+ template.plugins[0].source = {+ type: 'local',+ path: './packages/twenty-agent-skills/dist',+ };}, () => {const failures = collectFailures(metadata.assertMarketplaceTemplate);- assert.ok(failures.some((f) => f.includes('version must match')));+ assert.ok(failures.some((failure) => failure.includes('source.source must be local')));+ });+});++for (const [field, value] of [['installation', 'manual'], ['authentication', 'user-local']]) {+ test(`assertMarketplaceTemplate catches legacy ${field} policy`, () => {+ withJsonMutation(MARKETPLACE_TEMPLATE_PATH, (template) => {+ template.plugins[0].policy[field] = value;+ }, () => {+ const failures = collectFailures(metadata.assertMarketplaceTemplate);+ assert.ok(failures.some((failure) => failure.includes(`policy.${field} must be`)));+ });+ });+}++test('assertMarketplaceTemplate requires the installable distribution path', () => {+ withJsonMutation(MARKETPLACE_TEMPLATE_PATH, (template) => {+ template.plugins[0].source.path = './packages/twenty-agent-skills';+ }, () => {+ const failures = collectFailures(metadata.assertMarketplaceTemplate);+ assert.ok(failures.some((failure) => failure.includes('source.path must be ./packages/twenty-agent-skills/dist')));});});@@ -343,3 +398,52 @@ test('assertTestingGuidance catches missing manage-app test target instructions');});});++test('assertOperatingRulesSingleSource passes on current state', () => {+ assert.deepStrictEqual(collectFailures(crossDocContracts.assertOperatingRulesSingleSource), []);+});++test('assertOperatingRulesSingleSource catches AGENTS.md restating a rule', () => {+ const agentsPath = path.join(PLUGIN_ROOT, 'AGENTS.md');+ withFileMutation(agentsPath, (original) => `${original}\n1. **Confirm destructive operations.** Restated.\n`, () => {+ const failures = collectFailures(crossDocContracts.assertOperatingRulesSingleSource);+ assert.ok(+ failures.some((f) => f.includes('AGENTS.md') && f.includes('restates an operating rule')),+ `expected a restated-rule failure, got: ${failures.join('; ')}`,+ );+ });+});++test('assertOperatingRulesSingleSource catches AGENTS.md losing the pointer', () => {+ const agentsPath = path.join(PLUGIN_ROOT, 'AGENTS.md');+ withFileMutation(agentsPath, (original) => original.replaceAll('references/concepts/operating-rules.md', 'nowhere.md'), () => {+ const failures = collectFailures(crossDocContracts.assertOperatingRulesSingleSource);+ assert.ok(+ failures.some((f) => f.includes('AGENTS.md must point at')),+ `expected a missing-pointer failure, got: ${failures.join('; ')}`,+ );+ });+});++test('assertHowAppsWork catches a skill that does not reference operating-rules.md', () => {+ const skillPath = path.join(PLUGIN_ROOT, 'skills', 'develop-app', 'SKILL.md');+ withFileMutation(skillPath, (original) => original.replace('../../references/concepts/operating-rules.md', 'nowhere.md'), () => {+ const failures = collectFailures(references.assertHowAppsWork);+ assert.ok(+ failures.some((f) => f.includes('develop-app/SKILL.md') && f.includes('operating-rules.md')),+ `expected an operating-rules reference failure, got: ${failures.join('; ')}`,+ );+ });+});++test('assertOperatingRulesSingleSource catches prose copied from the rules file', () => {+ const agentsPath = path.join(PLUGIN_ROOT, 'AGENTS.md');+ const copiedSentence = 'Watch mode leaks file handles and produces ambiguous failure output in agent sandboxes.';+ withFileMutation(agentsPath, (original) => `${original}\n${copiedSentence}\n`, () => {+ const failures = collectFailures(crossDocContracts.assertOperatingRulesSingleSource);+ assert.ok(+ failures.some((f) => f.includes('AGENTS.md') && f.includes('copies a sentence')),+ `expected a copied-prose failure, got: ${failures.join('; ')}`,+ );+ });+});diff --git a/packages/twenty-agent-skills/scripts/build.js b/packages/twenty-agent-skills/scripts/build.jsnew file mode 100644index 00000000000..9a0847c933a--- /dev/null+++ b/packages/twenty-agent-skills/scripts/build.js@@ -0,0 +1,6 @@+#!/usr/bin/env node++import { buildDistribution } from './lib.js';++buildDistribution();+console.log('Twenty skills and Codex plugin distribution built in dist/.');diff --git a/packages/twenty-agent-skills/scripts/lib.js b/packages/twenty-agent-skills/scripts/lib.jsnew file mode 100644index 00000000000..72f69cf7ffd--- /dev/null+++ b/packages/twenty-agent-skills/scripts/lib.js@@ -0,0 +1,213 @@+import fs from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++import {+ CANONICAL_SKILL_NAMES,+ readText,+ listFiles,+} from './validators/lib.js';++const PACKAGE_ROOT = path.resolve(+ path.dirname(fileURLToPath(import.meta.url)),+ '..',+);+const DISTRIBUTION_ROOT = path.join(PACKAGE_ROOT, 'dist');++const SKILL_REFERENCE_PATTERN =+ /(?:\.\.\/\.\.\/)?references\/([A-Za-z0-9._/-]+\.md)/g;+const SIBLING_REFERENCE_PATTERN =+ /\.\.\/([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+\.md)/g;+const SAME_DIRECTORY_REFERENCE_PATTERN = /`([A-Za-z0-9._-]+\.md)`/g;++const findReferenceByBasename = ({ referencesRoot, basename }) => {+ for (const filePath of listFiles(referencesRoot)) {+ if (path.basename(filePath) === basename) {+ return path.relative(referencesRoot, filePath).split(path.sep).join('/');+ }+ }++ return undefined;+};++const rewriteSkillReferenceLinks = (skillMarkdown) =>+ skillMarkdown.replaceAll('../../references/', 'references/');++const collectSkillSeedReferences = (skillMarkdown) => {+ const seeds = new Set();++ for (const match of skillMarkdown.matchAll(SKILL_REFERENCE_PATTERN)) {+ seeds.add(match[1]);+ }++ return seeds;+};++// Expands the seed set with every reference doc reachable through relative+// mentions (`../<scope>/<file>.md` or same-directory `<file>.md`) so an+// installed skill never points at a file that was not copied with it.+const resolveReferenceClosure = (referencesRoot, seedReferences) => {+ const closure = new Set();+ const queue = [...seedReferences];++ while (queue.length > 0) {+ const relativeReference = queue.shift();++ if (closure.has(relativeReference)) {+ continue;+ }++ const absolutePath = path.join(referencesRoot, relativeReference);++ if (!fs.existsSync(absolutePath)) {+ throw new Error(+ `referenced doc does not exist: references/${relativeReference}`,+ );+ }++ closure.add(relativeReference);++ const contents = readText(absolutePath);+ const scope = path.dirname(relativeReference);++ for (const match of contents.matchAll(SIBLING_REFERENCE_PATTERN)) {+ queue.push(path.posix.join(match[1], match[2]));+ }++ for (const match of contents.matchAll(SAME_DIRECTORY_REFERENCE_PATTERN)) {+ const candidate = path.posix.join(scope, match[1]);++ // Backtick mentions also match non-file tokens such as+ // `themeCssVariables.font.size.md`; only real sibling docs are queued.+ if (fs.existsSync(path.join(referencesRoot, candidate))) {+ queue.push(candidate);+ continue;+ }++ // A bare mention that names a reference doc living in another scope would+ // otherwise be dropped here, shipping a skill that points at a file it+ // does not carry. Make the author write the explicit relative path.+ const elsewhere = findReferenceByBasename({+ referencesRoot,+ basename: match[1],+ });++ if (elsewhere) {+ throw new Error(+ `references/${relativeReference} mentions \`${match[1]}\` as a same-directory file, but it lives at references/${elsewhere}. Use an explicit relative path such as \`${path.posix.relative(scope, elsewhere)}\`.`,+ );+ }+ }+ }++ return closure;+};++const buildPortableSkills = ({+ sourceRoot = PACKAGE_ROOT,+ outputRoot,+ skillNames = CANONICAL_SKILL_NAMES,+}) => {+ const referencesRoot = path.join(sourceRoot, 'references');++ fs.rmSync(outputRoot, { recursive: true, force: true });++ for (const skillName of skillNames) {+ const sourceSkillPath = path.join(+ sourceRoot,+ 'skills',+ skillName,+ 'SKILL.md',+ );++ if (!fs.existsSync(sourceSkillPath)) {+ throw new Error(+ `canonical skill is missing: skills/${skillName}/SKILL.md`,+ );+ }++ const skillMarkdown = readText(sourceSkillPath);+ const outputSkillRoot = path.join(outputRoot, skillName);++ fs.cpSync(path.dirname(sourceSkillPath), outputSkillRoot, {+ recursive: true,+ });+ fs.writeFileSync(+ path.join(outputSkillRoot, 'SKILL.md'),+ rewriteSkillReferenceLinks(skillMarkdown),+ );++ const seedReferences = collectSkillSeedReferences(skillMarkdown);+ const referenceClosure = resolveReferenceClosure(+ referencesRoot,+ seedReferences,+ );++ for (const relativeReference of [...referenceClosure].sort()) {+ const outputReferencePath = path.join(+ outputSkillRoot,+ 'references',+ relativeReference,+ );++ fs.mkdirSync(path.dirname(outputReferencePath), { recursive: true });+ fs.copyFileSync(+ path.join(referencesRoot, relativeReference),+ outputReferencePath,+ );+ }+ }+};++const buildDistribution = ({+ sourceRoot = PACKAGE_ROOT,+ outputRoot = DISTRIBUTION_ROOT,+} = {}) => {+ const packageJson = JSON.parse(+ readText(path.join(sourceRoot, 'package.json')),+ );++ fs.rmSync(outputRoot, { recursive: true, force: true });+ fs.mkdirSync(outputRoot, { recursive: true });++ for (const relativePath of packageJson.files) {+ if (relativePath !== 'skills') {+ fs.cpSync(+ path.join(sourceRoot, relativePath),+ path.join(outputRoot, relativePath),+ {+ recursive: true,+ },+ );+ }+ }++ buildPortableSkills({+ sourceRoot,+ outputRoot: path.join(outputRoot, 'skills'),+ });+ const { name, version, description, license, files } = packageJson;++ fs.writeFileSync(+ path.join(outputRoot, 'package.json'),+ JSON.stringify(+ { name, version, description, license, private: true, files },+ null,+ 2,+ ) + '\n',+ );+};++export {+ PACKAGE_ROOT,+ DISTRIBUTION_ROOT,+ CANONICAL_SKILL_NAMES,+ readText,+ listFiles,+ rewriteSkillReferenceLinks,+ findReferenceByBasename,+ collectSkillSeedReferences,+ resolveReferenceClosure,+ buildPortableSkills,+ buildDistribution,+};diff --git a/packages/twenty-codex-plugin/scripts/setup-mcp.sh b/packages/twenty-agent-skills/scripts/setup-mcp.shsimilarity index 100%rename from packages/twenty-codex-plugin/scripts/setup-mcp.shrename to packages/twenty-agent-skills/scripts/setup-mcp.shdiff --git a/packages/twenty-agent-skills/scripts/validate-distribution.js b/packages/twenty-agent-skills/scripts/validate-distribution.jsnew file mode 100644index 00000000000..133c4be1126--- /dev/null+++ b/packages/twenty-agent-skills/scripts/validate-distribution.js@@ -0,0 +1,365 @@+#!/usr/bin/env node++import fs from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++import {+ DISTRIBUTION_ROOT,+ CANONICAL_SKILL_NAMES,+ readText,+ listFiles,+} from './lib.js';+import {+ isAllowedDocumentationHost,+ parseSkillFrontmatter,+} from './validators/lib.js';++// The portable skills must work after `npx skills add` copies a single skill+// directory into an agent's skill folder, outside the monorepo. Nothing in a+// skill may depend on the Codex wrapper, the monorepo layout, or a sibling+// skill directory.+const FORBIDDEN_PORTABILITY_FRAGMENTS = [+ 'packages/twenty-codex-plugin',+ 'packages/twenty-agent-skills',+ '.codex-plugin',+ 'openai.yaml',+ 'AGENTS.md',+ 'marketplace.json',+];++const PATH_LIKE_REFERENCE_PATTERN =+ /(?:(?:\.\.\/)+|references\/)[A-Za-z0-9._/-]+\.md/g;++const assertSkillDirectories = (skillsRoot, fail) => {+ if (!fs.existsSync(skillsRoot)) {+ fail('skills/ does not exist; run the build first');+ return [];+ }++ const skillDirectories = fs+ .readdirSync(skillsRoot, { withFileTypes: true })+ .filter((entry) => entry.isDirectory())+ .map((entry) => entry.name)+ .sort();++ for (const skillName of CANONICAL_SKILL_NAMES) {+ if (!skillDirectories.includes(skillName)) {+ fail(`portable skill is missing: ${skillName}`);+ }+ }++ for (const skillName of skillDirectories) {+ if (!CANONICAL_SKILL_NAMES.includes(skillName)) {+ fail(`unexpected skill directory: ${skillName}`);+ }+ }++ return skillDirectories;+};++const assertSkillFrontmatter = ({ skillsRoot, skillName, fail }) => {+ const skillPath = path.join(skillsRoot, skillName, 'SKILL.md');++ if (!fs.existsSync(skillPath)) {+ fail(`${skillName} is missing SKILL.md`);+ return;+ }++ const frontmatter = parseSkillFrontmatter(skillPath);++ if (!frontmatter) {+ fail(`${skillName}/SKILL.md is missing YAML frontmatter`);+ return;+ }++ if (frontmatter.name !== skillName) {+ fail(`${skillName}/SKILL.md frontmatter name must match its directory`);+ }++ if (!frontmatter.description) {+ fail(`${skillName}/SKILL.md frontmatter description is required`);+ }++ const frontmatterKeys = Object.keys(frontmatter);++ if (frontmatterKeys.some((key) => !['description', 'name'].includes(key))) {+ fail(+ `${skillName}/SKILL.md frontmatter should only include name and description`,+ );+ }++ if (!/^#+\s+When To Use\s*$/m.test(readText(skillPath))) {+ fail(`${skillName}/SKILL.md must include a "When To Use" section`);+ }+};++const assertSelfContainedReferences = ({ skillsRoot, skillName, fail }) => {+ const skillRoot = path.join(skillsRoot, skillName);++ for (const filePath of listFiles(skillRoot)) {+ const relativePath = path.relative(skillsRoot, filePath);++ // Optional Codex display metadata is carried by the same portable directory.+ if (+ path.relative(skillRoot, filePath) === path.join('agents', 'openai.yaml')+ ) {+ continue;+ }++ if (path.extname(filePath) !== '.md') {+ fail(+ `portable skills may only contain markdown and agents/openai.yaml: ${relativePath}`,+ );+ continue;+ }++ const contents = readText(filePath);++ for (const [reference] of contents.matchAll(PATH_LIKE_REFERENCE_PATTERN)) {+ const baseDirectory = reference.startsWith('references/')+ ? skillRoot+ : path.dirname(filePath);+ const resolvedPath = path.resolve(baseDirectory, reference);++ if (!resolvedPath.startsWith(skillRoot + path.sep)) {+ fail(+ `${relativePath} references a path outside its skill directory: ${reference}`,+ );+ continue;+ }++ if (!fs.existsSync(resolvedPath)) {+ fail(`${relativePath} references a missing file: ${reference}`);+ }+ }+ }+};++const assertPortability = ({ skillsRoot, skillName, fail }) => {+ const skillRoot = path.join(skillsRoot, skillName);++ for (const filePath of listFiles(skillRoot)) {+ const relativePath = path.relative(skillsRoot, filePath);+ const contents = readText(filePath);++ for (const fragment of FORBIDDEN_PORTABILITY_FRAGMENTS) {+ if (contents.includes(fragment)) {+ fail(+ `${relativePath} must not depend on non-portable content: ${fragment}`,+ );+ }+ }++ for (const [rawUrl] of contents.matchAll(/https?:\/\/[^\s"`'<>)]*/g)) {+ if (/[${}*]/.test(rawUrl)) {+ continue;+ }++ let parsedUrl;++ try {+ parsedUrl = new URL(rawUrl);+ } catch {+ continue;+ }++ if (!isAllowedDocumentationHost(parsedUrl.hostname)) {+ fail(+ `non-placeholder URL found in ${relativePath}: ${parsedUrl.origin}`,+ );+ }+ }++ if (/Bearer\s+(?!YOUR_API_KEY\b)[A-Za-z0-9._-]{20,}/.test(contents)) {+ fail(`possible bearer token found in ${relativePath}`);+ }++ if (/sk-[A-Za-z0-9_-]{20,}/.test(contents)) {+ fail(`possible API key found in ${relativePath}`);+ }+ }+};++// Installing two skills side by side must never produce two conflicting+// versions of a shared reference doc.+const assertSharedReferenceConsistency = (+ skillsRoot,+ skillDirectories,+ fail,+) => {+ const referenceContentsByRelativePath = new Map();++ for (const skillName of skillDirectories) {+ const referencesRoot = path.join(skillsRoot, skillName, 'references');++ if (!fs.existsSync(referencesRoot)) {+ continue;+ }++ for (const filePath of listFiles(referencesRoot)) {+ const relativeReference = path.relative(referencesRoot, filePath);+ const contents = readText(filePath);+ const existing = referenceContentsByRelativePath.get(relativeReference);++ if (existing && existing.contents !== contents) {+ fail(+ `shared reference diverges between ${existing.skillName} and ${skillName}: references/${relativeReference}`,+ );+ } else if (!existing) {+ referenceContentsByRelativePath.set(relativeReference, {+ skillName,+ contents,+ });+ }+ }+ }+};++const APP_SKILLS = ['create-app', 'develop-app', 'manage-app', 'publish-app'];+const OPERATING_RULES_REFERENCE = path.join(+ 'references',+ 'concepts',+ 'operating-rules.md',+);++// The operating rules are the one piece of guidance shared by every app skill.+// `skills add` copies a single skill directory, so each one must carry its own+// copy and link to it; assertSharedReferenceConsistency keeps the copies equal.+const assertOperatingRulesShipped = (skillsRoot, fail) => {+ for (const skillName of APP_SKILLS) {+ const skillPath = path.join(skillsRoot, skillName, 'SKILL.md');+ const operatingRulesPath = path.join(+ skillsRoot,+ skillName,+ OPERATING_RULES_REFERENCE,+ );++ if (!fs.existsSync(operatingRulesPath)) {+ fail(`${skillName} does not ship ${OPERATING_RULES_REFERENCE}`);+ }++ if (+ fs.existsSync(skillPath) &&+ !readText(skillPath).includes('references/concepts/operating-rules.md')+ ) {+ fail(+ `${skillName}/SKILL.md must link to references/concepts/operating-rules.md`,+ );+ }+ }+};++// Reference docs get mentioned in prose by bare filename. Those mentions escape+// PATH_LIKE_REFERENCE_PATTERN, so a skill can ship a doc that points at another+// doc it does not carry. Generic names such as README.md refer to the user's own+// files, so only basenames that exist somewhere in the collection are checked.+const assertNoDanglingDocMentions = (skillsRoot, skillDirectories, fail) => {+ const collectionDocNames = new Set();++ for (const skillName of skillDirectories) {+ for (const filePath of listFiles(path.join(skillsRoot, skillName))) {+ collectionDocNames.add(path.basename(filePath));+ }+ }++ for (const skillName of skillDirectories) {+ const skillRoot = path.join(skillsRoot, skillName);+ const bundledDocNames = new Set(+ listFiles(skillRoot).map((filePath) => path.basename(filePath)),+ );++ for (const filePath of listFiles(skillRoot)) {+ const relativePath = path.relative(skillsRoot, filePath);++ for (const [, docName] of readText(filePath).matchAll(+ /`([A-Za-z0-9_-]+\.md)`/g,+ )) {+ if (collectionDocNames.has(docName) && !bundledDocNames.has(docName)) {+ fail(+ `${relativePath} mentions ${docName}, which ${skillName} does not ship`,+ );+ }+ }+ }+ }+};++const assertSelfHostedSupport = (skillsRoot, fail) => {+ const createAppPath = path.join(skillsRoot, 'create-app', 'SKILL.md');+ const setupPath = path.join(+ skillsRoot,+ 'use-twenty-mcp',+ 'references',+ 'use-twenty-mcp',+ 'setup.md',+ );++ if (+ fs.existsSync(createAppPath) &&+ !readText(createAppPath).includes('self-hosted')+ ) {+ fail(+ 'create-app/SKILL.md must present self-hosted instances as a supported target',+ );+ }++ if (+ fs.existsSync(setupPath) &&+ !readText(setupPath).includes('Never require a `twenty.com` workspace')+ ) {+ fail('use-twenty-mcp setup.md must not require a twenty.com workspace');+ }+};++const validatePortableSkills = (skillsRoot, fail) => {+ const skillDirectories = assertSkillDirectories(skillsRoot, fail);++ for (const skillName of skillDirectories) {+ assertSkillFrontmatter({ skillsRoot, skillName, fail });+ assertSelfContainedReferences({ skillsRoot, skillName, fail });+ assertPortability({ skillsRoot, skillName, fail });+ }++ assertSharedReferenceConsistency(skillsRoot, skillDirectories, fail);+ assertOperatingRulesShipped(skillsRoot, fail);+ assertNoDanglingDocMentions(skillsRoot, skillDirectories, fail);+ assertSelfHostedSupport(skillsRoot, fail);+};++const isEntryPoint =+ process.argv[1] !== undefined &&+ path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);++if (isEntryPoint) {+ const failures = [];++ validatePortableSkills(path.join(DISTRIBUTION_ROOT, 'skills'), (message) =>+ failures.push(message),+ );++ if (failures.length > 0) {+ console.error('Twenty agent skills validation failed:');++ for (const failure of failures) {+ console.error(`- ${failure}`);+ }++ process.exit(1);+ }++ console.log('Twenty agent skills validation passed.');+}++export {+ FORBIDDEN_PORTABILITY_FRAGMENTS,+ assertSkillDirectories,+ assertSkillFrontmatter,+ assertSelfContainedReferences,+ assertPortability,+ assertSharedReferenceConsistency,+ assertOperatingRulesShipped,+ assertNoDanglingDocMentions,+ assertSelfHostedSupport,+ validatePortableSkills,+};diff --git a/packages/twenty-codex-plugin/scripts/validate.js b/packages/twenty-agent-skills/scripts/validate-source.jssimilarity index 60%rename from packages/twenty-codex-plugin/scripts/validate.jsrename to packages/twenty-agent-skills/scripts/validate-source.jsindex c36aae9f287..0b2709d8296 100644--- a/packages/twenty-codex-plugin/scripts/validate.js+++ b/packages/twenty-agent-skills/scripts/validate-source.js@@ -1,11 +1,11 @@#!/usr/bin/env node-const metadata = require('./validators/metadata');-const assets = require('./validators/assets');-const skills = require('./validators/skills');-const references = require('./validators/references');-const crossDocContracts = require('./validators/cross-doc-contracts');-const setupHelper = require('./validators/setup-helper');+import * as metadata from './validators/metadata.js';+import * as assets from './validators/assets.js';+import * as skills from './validators/skills.js';+import * as references from './validators/references.js';+import * as crossDocContracts from './validators/cross-doc-contracts.js';+import * as setupHelper from './validators/setup-helper.js';const failures = [];const fail = (message) => failures.push(message);@@ -20,6 +20,7 @@ skills.assertSkillTriggerPhrases(fail);skills.assertNoLegacySkillReferences(fail);references.assertReferences(fail);references.assertHowAppsWork(fail);+crossDocContracts.assertOperatingRulesSingleSource(fail);crossDocContracts.assertTwentyMcpFormattingContract(fail);crossDocContracts.assertFrontComponentGuidance(fail);crossDocContracts.assertCliGuidanceSplit(fail);@@ -27,7 +28,7 @@ crossDocContracts.assertTestingGuidance(fail);setupHelper.assertSetupHelper(fail);if (failures.length > 0) {- console.error('Twenty Codex plugin validation failed:');+ console.error('Twenty Agent Skills source validation failed:');for (const failure of failures) {console.error(`- ${failure}`);@@ -36,4 +37,4 @@ if (failures.length > 0) {process.exit(1);}-console.log('Twenty Codex plugin validation passed.');+console.log('Twenty Agent Skills source validation passed.');diff --git a/packages/twenty-codex-plugin/scripts/validators/assets.js b/packages/twenty-agent-skills/scripts/validators/assets.jssimilarity index 92%rename from packages/twenty-codex-plugin/scripts/validators/assets.jsrename to packages/twenty-agent-skills/scripts/validators/assets.jsindex 07b262f8127..6148bb7cf35 100644--- a/packages/twenty-codex-plugin/scripts/validators/assets.js+++ b/packages/twenty-agent-skills/scripts/validators/assets.js@@ -1,18 +1,18 @@-const fs = require('node:fs');-const path = require('node:path');+import fs from 'node:fs';+import path from 'node:path';-const {+import {MIN_LOGO_DIMENSION,readText,readPngDimensions,createJsonReaders,createInterfacePathResolver,-} = require('./lib');+} from './lib.js';const assertAssets = (fail) => {const { readJson } = createJsonReaders(fail);const resolveInterfacePath = createInterfacePathResolver(fail);- const pluginJson = readJson('packages/twenty-codex-plugin/.codex-plugin/plugin.json');+ const pluginJson = readJson('packages/twenty-agent-skills/.codex-plugin/plugin.json');const interfaceMetadata = pluginJson?.interface;if (!interfaceMetadata) {@@ -78,4 +78,4 @@ const assertAssets = (fail) => {}};-module.exports = { assertAssets };+export { assertAssets };diff --git a/packages/twenty-codex-plugin/scripts/validators/cross-doc-contracts.js b/packages/twenty-agent-skills/scripts/validators/cross-doc-contracts.jssimilarity index 79%rename from packages/twenty-codex-plugin/scripts/validators/cross-doc-contracts.jsrename to packages/twenty-agent-skills/scripts/validators/cross-doc-contracts.jsindex 11640a56ab8..de0a779ec38 100644--- a/packages/twenty-codex-plugin/scripts/validators/cross-doc-contracts.js+++ b/packages/twenty-agent-skills/scripts/validators/cross-doc-contracts.js@@ -1,6 +1,7 @@-const path = require('node:path');+import fs from 'node:fs';+import path from 'node:path';-const { PLUGIN_ROOT, listFiles, readText } = require('./lib');+import { PLUGIN_ROOT, listFiles, readText } from './lib.js';const assertTwentyMcpFormattingContract = (fail) => {const skillPath = path.join(PLUGIN_ROOT, 'skills/use-twenty-mcp/SKILL.md');@@ -324,11 +325,11 @@ const assertTestingGuidance = (fail) => {const manageSkillPath = path.join(PLUGIN_ROOT, 'skills/manage-app/SKILL.md');const testsPath = path.join(PLUGIN_ROOT, 'references/develop-app/tests.md');const cliAndSyncPath = path.join(PLUGIN_ROOT, 'references/manage-app/cli-and-sync.md');- const agentsPath = path.join(PLUGIN_ROOT, 'AGENTS.md');+ const operatingRulesPath = path.join(PLUGIN_ROOT, 'references/concepts/operating-rules.md');const manageSkill = readText(manageSkillPath);const tests = readText(testsPath);const cliAndSync = readText(cliAndSyncPath);- const agents = readText(agentsPath);+ const operatingRules = readText(operatingRulesPath);const requiredManageFragments = ['run tests for my Twenty app',@@ -370,19 +371,93 @@ const assertTestingGuidance = (fail) => {}}- const requiredAgentsFragments = [+ const requiredOperatingRulesFragments = ['TWENTY_API_URL=http://localhost:2021 yarn test','Integration tests must target the isolated test instance on port `2021`',];- for (const fragment of requiredAgentsFragments) {- if (!agents.includes(fragment)) {- fail(`AGENTS.md is missing durable test target guidance: ${fragment}`);+ for (const fragment of requiredOperatingRulesFragments) {+ if (!operatingRules.includes(fragment)) {+ fail(`operating-rules.md is missing durable test target guidance: ${fragment}`);}}};-module.exports = {+const OPERATING_RULE_HEADLINES = [+ '**Bounded sync only.**',+ '**Do not run broad validation unless it is requested.**',+ '**Use `yarn twenty dev:add` for new entities.**',+ '**Confirm destructive operations.**',+ '**Any Twenty instance is a valid target.**',+ '**Workspace URLs and credentials stay user-local.**',+];++// Every entry point links to the operating rules to keep authored guidance+// from drifting between skills and the Codex wrapper.+const assertOperatingRulesSingleSource = (fail) => {+ const operatingRulesPath = path.join(PLUGIN_ROOT, 'references/concepts/operating-rules.md');++ if (!fs.existsSync(operatingRulesPath)) {+ fail('required reference is missing: references/concepts/operating-rules.md');+ return;+ }++ const operatingRules = readText(operatingRulesPath);++ for (const headline of OPERATING_RULE_HEADLINES) {+ if (!operatingRules.includes(headline)) {+ fail(`operating-rules.md is missing a durable rule: ${headline}`);+ }+ }++ const restatingDocumentPaths = [+ path.join(PLUGIN_ROOT, 'AGENTS.md'),+ ...listFiles(path.join(PLUGIN_ROOT, 'skills')).filter((filePath) => filePath.endsWith('.md')),+ ];++ for (const documentPath of restatingDocumentPaths) {+ const relativePath = path.relative(PLUGIN_ROOT, documentPath);+ const contents = readText(documentPath);++ for (const headline of OPERATING_RULE_HEADLINES) {+ if (contents.includes(headline)) {+ fail(`${relativePath} restates an operating rule instead of linking to operating-rules.md: ${headline}`);+ }+ }+ }++ const agents = readText(path.join(PLUGIN_ROOT, 'AGENTS.md'));++ if (!agents.includes('references/concepts/operating-rules.md')) {+ fail('AGENTS.md must point at references/concepts/operating-rules.md for the durable operating rules');+ }++ // Headlines catch a copied rule list. Copied prose is the other way a second+ // version of a rule appears and then drifts, so sentences from the rule+ // bodies must not be pasted into an entry point either. A skill applying a+ // rule in its own words at the point of use is expected and not flagged.+ const ruleBodySentences = operatingRules+ .split('\n')+ .filter((line) => /^\d+\.\s+\*\*/.test(line))+ .flatMap((line) => line.replace(/^\d+\.\s+\*\*[^*]+\*\*\s*/, '').split('. '))+ .map((sentence) => sentence.trim())+ .filter((sentence) => sentence.length >= 60);++ for (const documentPath of restatingDocumentPaths) {+ const relativePath = path.relative(PLUGIN_ROOT, documentPath);+ const contents = readText(documentPath);++ for (const sentence of ruleBodySentences) {+ if (contents.includes(sentence)) {+ fail(`${relativePath} copies a sentence from operating-rules.md instead of linking to it: "${sentence.slice(0, 60)}..."`);+ }+ }+ }+};++export {+ OPERATING_RULE_HEADLINES,+ assertOperatingRulesSingleSource,assertTwentyMcpFormattingContract,assertFrontComponentGuidance,assertCliGuidanceSplit,diff --git a/packages/twenty-codex-plugin/scripts/validators/lib.js b/packages/twenty-agent-skills/scripts/validators/lib.jssimilarity index 77%rename from packages/twenty-codex-plugin/scripts/validators/lib.jsrename to packages/twenty-agent-skills/scripts/validators/lib.jsindex 1e44eacf21f..5d3dcb9d156 100644--- a/packages/twenty-codex-plugin/scripts/validators/lib.js+++ b/packages/twenty-agent-skills/scripts/validators/lib.js@@ -1,11 +1,24 @@-const fs = require('node:fs');-const path = require('node:path');--const PLUGIN_ROOT = path.resolve(__dirname, '..', '..');+import fs from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++const PLUGIN_ROOT = path.resolve(+ path.dirname(fileURLToPath(import.meta.url)),+ '..',+ '..',+);const REPO_ROOT = path.resolve(PLUGIN_ROOT, '..', '..');const PUBLIC_DOCS_MCP_SERVER_NAME = 'twenty-docs';const PUBLIC_DOCS_MCP_URL = 'https://docs.twenty.com/mcp';+const CANONICAL_SKILL_NAMES = [+ 'create-app',+ 'develop-app',+ 'manage-app',+ 'publish-app',+ 'use-twenty-mcp',+];+const LEGACY_SKILL_NAMES = ['app-readme-and-visuals','build-app-features',@@ -16,7 +29,15 @@ const LEGACY_SKILL_NAMES = [];const VALID_CAPABILITIES = new Set(['Interactive', 'Read', 'Write']);-const VALID_CATEGORIES = new Set(['Coding', 'Productivity', 'Communication', 'Data', 'Design', 'Marketing', 'Sales']);+const VALID_CATEGORIES = new Set([+ 'Coding',+ 'Productivity',+ 'Communication',+ 'Data',+ 'Design',+ 'Marketing',+ 'Sales',+]);const SHORT_DESCRIPTION_MAX = 64;const MIN_LOGO_DIMENSION = 256;@@ -29,6 +50,11 @@ const listFiles = (directory) => {for (const entry of entries) {const absolutePath = path.join(directory, entry.name);+ // Generated bundles have their own validation and may be stale during edits.+ if (absolutePath === path.join(PLUGIN_ROOT, 'dist')) {+ continue;+ }+if (entry.isDirectory()) {files.push(...listFiles(absolutePath));} else {@@ -36,7 +62,8 @@ const listFiles = (directory) => {}}- return files;+ // Sorted so validator output is stable regardless of readdir order.+ return files.sort();};const parseSkillFrontmatter = (skillPath) => {@@ -61,7 +88,9 @@ const parseSkillFrontmatter = (skillPath) => {};const parseQuotedYamlField = (contents, fieldName) => {- const match = contents.match(new RegExp(`^\\s+${fieldName}:\\s+"([^"]+)"\\s*$`, 'm'));+ const match = contents.match(+ new RegExp(`^\\s+${fieldName}:\\s+"([^"]+)"\\s*$`, 'm'),+ );return match?.[1];};@@ -83,6 +112,7 @@ const isAllowedDocumentationHost = (hostname) => {host === 'app.twenty.com' ||host === 'twenty.com' ||host === 'docs.twenty.com' ||+ host === 'skills.sh' ||host === 'www.docker.com' ||host === 'github.com' ||host === 'www.w3.org' ||@@ -95,7 +125,9 @@ const isAllowedDocumentationHost = (hostname) => {const readPngDimensions = (filePath) => {const buffer = fs.readFileSync(filePath);- const signature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);+ const signature = Buffer.from([+ 0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,+ ]);if (buffer.length < 24 || !buffer.subarray(0, 8).equals(signature)) {return undefined;@@ -149,19 +181,25 @@ const createInterfacePathResolver = (fail) => (relativePath) => {const resolvedPath = path.resolve(PLUGIN_ROOT, relativePath.slice(2));// Reject ../ traversal that escapes the plugin directory after normalization- if (resolvedPath !== PLUGIN_ROOT && !resolvedPath.startsWith(PLUGIN_ROOT + path.sep)) {- fail(`interface path must stay within the plugin directory (got: ${relativePath})`);+ if (+ resolvedPath !== PLUGIN_ROOT &&+ !resolvedPath.startsWith(PLUGIN_ROOT + path.sep)+ ) {+ fail(+ `interface path must stay within the plugin directory (got: ${relativePath})`,+ );return undefined;}return resolvedPath;};-module.exports = {+export {PLUGIN_ROOT,REPO_ROOT,PUBLIC_DOCS_MCP_SERVER_NAME,PUBLIC_DOCS_MCP_URL,+ CANONICAL_SKILL_NAMES,LEGACY_SKILL_NAMES,VALID_CAPABILITIES,VALID_CATEGORIES,diff --git a/packages/twenty-codex-plugin/scripts/validators/metadata.js b/packages/twenty-agent-skills/scripts/validators/metadata.jssimilarity index 82%rename from packages/twenty-codex-plugin/scripts/validators/metadata.jsrename to packages/twenty-agent-skills/scripts/validators/metadata.jsindex 268d57bc6be..819e65f5c23 100644--- a/packages/twenty-codex-plugin/scripts/validators/metadata.js+++ b/packages/twenty-agent-skills/scripts/validators/metadata.js@@ -1,7 +1,7 @@-const fs = require('node:fs');-const path = require('node:path');+import fs from 'node:fs';+import path from 'node:path';-const {+import {PLUGIN_ROOT,REPO_ROOT,PUBLIC_DOCS_MCP_SERVER_NAME,@@ -13,13 +13,13 @@ const {listFiles,isAllowedDocumentationHost,createJsonReaders,-} = require('./lib');+} from './lib.js';const assertJsonMetadata = (fail) => {const { readJson, readOptionalJson } = createJsonReaders(fail);- const packageJson = readJson('packages/twenty-codex-plugin/package.json');- const pluginJson = readJson('packages/twenty-codex-plugin/.codex-plugin/plugin.json');- const mcpJson = readJson('packages/twenty-codex-plugin/.mcp.json');+ const packageJson = readJson('packages/twenty-agent-skills/package.json');+ const pluginJson = readJson('packages/twenty-agent-skills/.codex-plugin/plugin.json');+ const mcpJson = readJson('packages/twenty-agent-skills/.mcp.json');const marketplaceJson = readOptionalJson('.agents/plugins/marketplace.json');if (packageJson?.version !== pluginJson?.version) {@@ -70,12 +70,12 @@ const assertJsonMetadata = (fail) => {if (marketplaceJson && !marketplaceEntry) {fail('.agents/plugins/marketplace.json includes plugins but not the twenty plugin entry');- } else if (marketplaceEntry && marketplaceEntry.source?.path !== './packages/twenty-codex-plugin') {- fail('marketplace twenty source path must be ./packages/twenty-codex-plugin');+ } else if (marketplaceEntry && marketplaceEntry.source?.path !== './packages/twenty-agent-skills/dist') {+ fail('marketplace twenty source path must be ./packages/twenty-agent-skills/dist');}if (fs.existsSync(path.join(REPO_ROOT, 'plugins', 'twenty'))) {- fail('legacy plugins/twenty path must not exist; use packages/twenty-codex-plugin directly');+ fail('legacy plugins/twenty path must not exist; use packages/twenty-agent-skills/dist');}};@@ -83,7 +83,7 @@ const assertNoBundledMcpConfig = (fail) => {const gitignorePath = path.join(PLUGIN_ROOT, '.gitignore');if (fs.existsSync(gitignorePath) && readText(gitignorePath).split(/\r?\n/).includes('.mcp.json')) {- fail('packages/twenty-codex-plugin/.gitignore must not ignore the public .mcp.json');+ fail('packages/twenty-agent-skills/.gitignore must not ignore the public .mcp.json');}for (const filePath of listFiles(PLUGIN_ROOT)) {@@ -135,7 +135,7 @@ const assertNoBundledMcpConfig = (fail) => {const assertInterfaceFields = (fail) => {const { readJson } = createJsonReaders(fail);- const pluginJson = readJson('packages/twenty-codex-plugin/.codex-plugin/plugin.json');+ const pluginJson = readJson('packages/twenty-agent-skills/.codex-plugin/plugin.json');const interfaceMetadata = pluginJson?.interface;if (!interfaceMetadata || typeof interfaceMetadata !== 'object' || Array.isArray(interfaceMetadata)) {@@ -204,15 +204,23 @@ const assertInterfaceFields = (fail) => {const assertMarketplaceTemplate = (fail) => {const { readJson, readOptionalJson } = createJsonReaders(fail);- const templatePath = 'packages/twenty-codex-plugin/templates/marketplace.example.json';+ const templatePath = 'packages/twenty-agent-skills/templates/marketplace.example.json';const template = readOptionalJson(templatePath);- const pluginJson = readJson('packages/twenty-codex-plugin/.codex-plugin/plugin.json');+ const pluginJson = readJson('packages/twenty-agent-skills/.codex-plugin/plugin.json');if (!template) {fail(`marketplace template is missing at ${templatePath}`);return;}+ if (typeof template.name !== 'string' || template.name.trim().length === 0) {+ fail(`${templatePath} name must be a non-empty string`);+ }++ if (typeof template.interface?.displayName !== 'string' || template.interface.displayName.trim().length === 0) {+ fail(`${templatePath} interface.displayName must be a non-empty string`);+ }+const entries = template.plugins;if (!Array.isArray(entries) || entries.length === 0) {@@ -227,20 +235,20 @@ const assertMarketplaceTemplate = (fail) => {return;}- if (twentyEntry.version !== pluginJson?.version) {- fail(`${templatePath} twenty.version must match plugin.json version`);+ if (twentyEntry.source?.source !== 'local') {+ fail(`${templatePath} twenty.source.source must be local`);}- if (twentyEntry.source?.path !== './packages/twenty-codex-plugin') {- fail(`${templatePath} twenty.source.path must be ./packages/twenty-codex-plugin`);+ if (twentyEntry.source?.path !== './packages/twenty-agent-skills/dist') {+ fail(`${templatePath} twenty.source.path must be ./packages/twenty-agent-skills/dist`);}- if (!twentyEntry.policy?.installation) {- fail(`${templatePath} twenty.policy.installation is required`);+ if (!['NOT_AVAILABLE', 'AVAILABLE', 'INSTALLED_BY_DEFAULT'].includes(twentyEntry.policy?.installation)) {+ fail(`${templatePath} twenty.policy.installation must be NOT_AVAILABLE, AVAILABLE, or INSTALLED_BY_DEFAULT`);}- if (!twentyEntry.policy?.authentication) {- fail(`${templatePath} twenty.policy.authentication is required`);+ if (!['ON_INSTALL', 'ON_USE'].includes(twentyEntry.policy?.authentication)) {+ fail(`${templatePath} twenty.policy.authentication must be ON_INSTALL or ON_USE`);}if (twentyEntry.category !== pluginJson?.interface?.category) {@@ -248,7 +256,7 @@ const assertMarketplaceTemplate = (fail) => {}};-module.exports = {+export {assertJsonMetadata,assertNoBundledMcpConfig,assertInterfaceFields,diff --git a/packages/twenty-codex-plugin/scripts/validators/references.js b/packages/twenty-agent-skills/scripts/validators/references.jssimilarity index 90%rename from packages/twenty-codex-plugin/scripts/validators/references.jsrename to packages/twenty-agent-skills/scripts/validators/references.jsindex 261a641af71..581a71c9485 100644--- a/packages/twenty-codex-plugin/scripts/validators/references.js+++ b/packages/twenty-agent-skills/scripts/validators/references.js@@ -1,7 +1,7 @@-const fs = require('node:fs');-const path = require('node:path');+import fs from 'node:fs';+import path from 'node:path';-const { PLUGIN_ROOT, readText } = require('./lib');+import { PLUGIN_ROOT, readText } from './lib.js';const REQUIRED_REFERENCES = ['references/design/front-component-ui.md',@@ -16,6 +16,7 @@ const REQUIRED_REFERENCES = ['references/manage-app/cli-and-sync.md','references/publish-app/prepare-for-app-store.md','references/concepts/how-apps-work.md',+ 'references/concepts/operating-rules.md','references/use-twenty-mcp/setup.md','references/use-twenty-mcp/result-formatting.md',];@@ -89,10 +90,14 @@ const assertHowAppsWork = (fail) => {if (!skill.includes('references/concepts/how-apps-work.md')) {fail(`${skillRelPath} must reference how-apps-work.md`);}++ if (!skill.includes('references/concepts/operating-rules.md')) {+ fail(`${skillRelPath} must reference operating-rules.md`);+ }}};-module.exports = {+export {REQUIRED_REFERENCES,assertReferences,assertHowAppsWork,diff --git a/packages/twenty-codex-plugin/scripts/validators/setup-helper.js b/packages/twenty-agent-skills/scripts/validators/setup-helper.jssimilarity index 89%rename from packages/twenty-codex-plugin/scripts/validators/setup-helper.jsrename to packages/twenty-agent-skills/scripts/validators/setup-helper.jsindex 600a16980d2..5c23f1ceac7 100644--- a/packages/twenty-codex-plugin/scripts/validators/setup-helper.js+++ b/packages/twenty-agent-skills/scripts/validators/setup-helper.js@@ -1,7 +1,7 @@-const path = require('node:path');-const { spawnSync } = require('node:child_process');+import path from 'node:path';+import { spawnSync } from 'node:child_process';-const { PLUGIN_ROOT } = require('./lib');+import { PLUGIN_ROOT } from './lib.js';const URL_NORMALIZATION_CASES = [['myworkspace.localhost:3001', 'http://myworkspace.localhost:3001/mcp'],@@ -45,4 +45,4 @@ const assertSetupHelper = (fail) => {}};-module.exports = { assertSetupHelper };+export { assertSetupHelper };diff --git a/packages/twenty-codex-plugin/scripts/validators/skills.js b/packages/twenty-agent-skills/scripts/validators/skills.jssimilarity index 69%rename from packages/twenty-codex-plugin/scripts/validators/skills.jsrename to packages/twenty-agent-skills/scripts/validators/skills.jsindex d46daa406e1..e6d75527533 100644--- a/packages/twenty-codex-plugin/scripts/validators/skills.js+++ b/packages/twenty-agent-skills/scripts/validators/skills.js@@ -1,22 +1,15 @@-const fs = require('node:fs');-const path = require('node:path');+import fs from 'node:fs';+import path from 'node:path';-const {+import {PLUGIN_ROOT,+ CANONICAL_SKILL_NAMES,LEGACY_SKILL_NAMES,readText,listFiles,parseSkillFrontmatter,parseQuotedYamlField,-} = require('./lib');--const EXPECTED_CANONICAL_SKILLS = [- 'create-app',- 'develop-app',- 'manage-app',- 'publish-app',- 'use-twenty-mcp',-];+} from './lib.js';const assertSkills = (fail) => {const skillsRoot = path.join(PLUGIN_ROOT, 'skills');@@ -26,7 +19,7 @@ const assertSkills = (fail) => {.map((entry) => entry.name).sort();- for (const skillName of EXPECTED_CANONICAL_SKILLS) {+ for (const skillName of CANONICAL_SKILL_NAMES) {if (!skillDirectories.includes(skillName)) {fail(`canonical skill is missing: ${skillName}`);}@@ -34,13 +27,20 @@ const assertSkills = (fail) => {for (const skillName of LEGACY_SKILL_NAMES) {if (skillDirectories.includes(skillName)) {- fail(`legacy skill directory must be transferred out of skills/: ${skillName}`);+ fail(+ `legacy skill directory must be transferred out of skills/: ${skillName}`,+ );}}for (const skillName of skillDirectories) {const skillPath = path.join(skillsRoot, skillName, 'SKILL.md');- const agentsPath = path.join(skillsRoot, skillName, 'agents', 'openai.yaml');+ const agentsPath = path.join(+ skillsRoot,+ skillName,+ 'agents',+ 'openai.yaml',+ );if (!fs.existsSync(skillPath)) {fail(`${skillName} is missing SKILL.md`);@@ -62,8 +62,12 @@ const assertSkills = (fail) => {fail(`${skillName}/SKILL.md frontmatter description is required`);}- if (frontmatterKeys.some((key) => !['description', 'name'].includes(key))) {- fail(`${skillName}/SKILL.md frontmatter should only include name and description`);+ if (+ frontmatterKeys.some((key) => !['description', 'name'].includes(key))+ ) {+ fail(+ `${skillName}/SKILL.md frontmatter should only include name and description`,+ );}}@@ -74,7 +78,10 @@ const assertSkills = (fail) => {const agentsYaml = readText(agentsPath);const displayName = parseQuotedYamlField(agentsYaml, 'display_name');- const shortDescription = parseQuotedYamlField(agentsYaml, 'short_description');+ const shortDescription = parseQuotedYamlField(+ agentsYaml,+ 'short_description',+ );const defaultPrompt = parseQuotedYamlField(agentsYaml, 'default_prompt');if (!displayName) {@@ -82,15 +89,23 @@ const assertSkills = (fail) => {}if (!shortDescription) {- fail(`${skillName}/agents/openai.yaml is missing interface.short_description`);+ fail(+ `${skillName}/agents/openai.yaml is missing interface.short_description`,+ );} else if (shortDescription.length > 64) {- fail(`${skillName}/agents/openai.yaml short_description must be 64 characters or fewer`);+ fail(+ `${skillName}/agents/openai.yaml short_description must be 64 characters or fewer`,+ );}if (!defaultPrompt) {- fail(`${skillName}/agents/openai.yaml is missing interface.default_prompt`);+ fail(+ `${skillName}/agents/openai.yaml is missing interface.default_prompt`,+ );} else if (!defaultPrompt.includes(`$${skillName}`)) {- fail(`${skillName}/agents/openai.yaml default_prompt must mention $${skillName}`);+ fail(+ `${skillName}/agents/openai.yaml default_prompt must mention $${skillName}`,+ );}}};@@ -112,7 +127,9 @@ const assertSkillTriggerPhrases = (fail) => {const contents = readText(skillPath);if (!/^#+\s+When To Use\s*$/m.test(contents)) {- fail(`${skillName}/SKILL.md must include a "When To Use" section with representative trigger phrases`);+ fail(+ `${skillName}/SKILL.md must include a "When To Use" section with representative trigger phrases`,+ );}}};@@ -130,7 +147,9 @@ const assertNoLegacySkillReferences = (fail) => {for (const legacySkillName of LEGACY_SKILL_NAMES) {if (contents.includes(`name: ${legacySkillName}`)) {- fail(`${relativePath} must not declare legacy skill name ${legacySkillName}`);+ fail(+ `${relativePath} must not declare legacy skill name ${legacySkillName}`,+ );}const mentionPattern =@@ -141,14 +160,16 @@ const assertNoLegacySkillReferences = (fail) => {);if (mentionPattern.test(contents)) {- fail(`${relativePath} must not mention legacy skill name ${legacySkillName}`);+ fail(+ `${relativePath} must not mention legacy skill name ${legacySkillName}`,+ );}}}};-module.exports = {- EXPECTED_CANONICAL_SKILLS,+export {+ CANONICAL_SKILL_NAMES,assertSkills,assertSkillTriggerPhrases,assertNoLegacySkillReferences,diff --git a/packages/twenty-agent-skills/scripts/verify-install.js b/packages/twenty-agent-skills/scripts/verify-install.jsnew file mode 100644index 00000000000..ee4df1fe0bd--- /dev/null+++ b/packages/twenty-agent-skills/scripts/verify-install.js@@ -0,0 +1,144 @@+#!/usr/bin/env node++import fs from 'node:fs';+import path from 'node:path';++import {+ DISTRIBUTION_ROOT,+ CANONICAL_SKILL_NAMES,+ listFiles,+ readText,+} from './lib.js';+import {+ assertSelfContainedReferences,+ assertSkillFrontmatter,+} from './validate-distribution.js';++const [installRoot, ...requestedSkills] = process.argv.slice(2);++if (!installRoot) {+ console.error(+ 'usage: verify-install.js <install-root> [skill-name...]\n' ++ 'Verifies that skills installed by the `skills` CLI are complete and self-contained.',+ );+ process.exit(1);+}++const skillNames =+ requestedSkills.length > 0 ? requestedSkills : CANONICAL_SKILL_NAMES;++// assertSelfContainedReferences resolves references to absolute paths, so the+// roots it compares them against must be absolute too.+const absoluteInstallRoot = path.resolve(installRoot);++// `skills add` writes to an agent-specific directory (.agents/skills, .claude/skills,+// .codex/skills, ...) and may symlink between them, so the installed copies are+// discovered rather than assumed.+const findInstalledSkillRoots = ({ root, skillName }) => {+ const found = [];+ const walk = (directory) => {+ for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {+ const absolutePath = path.join(directory, entry.name);++ if (+ !fs.existsSync(absolutePath) ||+ !fs.statSync(absolutePath).isDirectory()+ ) {+ continue;+ }++ if (+ entry.name === skillName &&+ fs.existsSync(path.join(absolutePath, 'SKILL.md'))+ ) {+ found.push(absolutePath);+ continue;+ }++ walk(absolutePath);+ }+ };++ walk(root);++ return found;+};++const relativeFiles = (root) =>+ listFiles(root)+ .map((filePath) => path.relative(root, filePath))+ .sort();++const failures = [];+const fail = (message) => failures.push(message);++for (const skillName of skillNames) {+ const sourceRoot = path.join(DISTRIBUTION_ROOT, 'skills', skillName);+ const installedRoots = findInstalledSkillRoots({+ root: absoluteInstallRoot,+ skillName,+ });++ if (installedRoots.length === 0) {+ fail(+ `${skillName} was not installed anywhere under ${absoluteInstallRoot}`,+ );+ continue;+ }++ const expectedFiles = relativeFiles(sourceRoot);++ for (const installedRoot of installedRoots) {+ const location = path.relative(absoluteInstallRoot, installedRoot);+ const installedFiles = relativeFiles(installedRoot);++ for (const relativePath of expectedFiles) {+ if (!installedFiles.includes(relativePath)) {+ fail(`${location} is missing ${relativePath}`);+ continue;+ }++ if (+ readText(path.join(sourceRoot, relativePath)) !==+ readText(path.join(installedRoot, relativePath))+ ) {+ fail(`${location} installed a modified ${relativePath}`);+ }+ }++ for (const relativePath of installedFiles) {+ if (!expectedFiles.includes(relativePath)) {+ fail(`${location} has an unexpected ${relativePath}`);+ }+ }++ // Every relative link inside every installed file must resolve inside the+ // installed directory; that is the "no manual fixes after installation" bar.+ assertSelfContainedReferences({+ skillsRoot: path.dirname(installedRoot),+ skillName,+ fail,+ });+ assertSkillFrontmatter({+ skillsRoot: path.dirname(installedRoot),+ skillName,+ fail,+ });++ console.log(+ `${skillName}: ${installedFiles.length} files verified in ${location}`,+ );+ }+}++if (failures.length > 0) {+ console.error('Installed Twenty agent skills failed verification:');++ for (const failure of failures) {+ console.error(`- ${failure}`);+ }++ process.exit(1);+}++console.log(`Verified ${skillNames.length} installed skill(s).`);diff --git a/packages/twenty-codex-plugin/skills/create-app/SKILL.md b/packages/twenty-agent-skills/skills/create-app/SKILL.mdsimilarity index 94%rename from packages/twenty-codex-plugin/skills/create-app/SKILL.mdrename to packages/twenty-agent-skills/skills/create-app/SKILL.mdindex 8af57cccbd8..ed0e3804234 100644--- a/packages/twenty-codex-plugin/skills/create-app/SKILL.md+++ b/packages/twenty-agent-skills/skills/create-app/SKILL.md@@ -18,7 +18,7 @@ Do not use this skill when the app already exists — use `develop-app` to add f# Quickstart an App-For background on how Twenty apps work — the SDK packages, remotes, sync lifecycle, and rendering model — read `../../references/concepts/how-apps-work.md`.+For background on how Twenty apps work — the SDK packages, remotes, sync lifecycle, and rendering model — read `../../references/concepts/how-apps-work.md`. Cross-skill operating rules that apply to every Twenty app task are in `../../references/concepts/operating-rules.md`; they are authoritative and not restated per skill.Use this as the default way to start an app unless the user gives different instructions.@@ -94,5 +94,5 @@ If the user still wants the local Docker path and Docker is missing, share thisOnly proceed to these when the user explicitly asks:- Use `develop-app` when the user wants to add objects, fields, logic functions, roles, views, navigation, page layouts, skills, agents, or front component registrations.-- Use `references/design/front-component-ui.md` when the user wants to design or improve the UI of a Twenty front component.+- Use `../../references/design/front-component-ui.md` when the user wants to design or improve the UI of a Twenty front component.- When the user later makes changes to app entities, use `yarn twenty apply` to sync those changes. See the `manage-app` skill for sync workflow.diff --git a/packages/twenty-codex-plugin/skills/create-app/agents/openai.yaml b/packages/twenty-agent-skills/skills/create-app/agents/openai.yamlsimilarity index 100%rename from packages/twenty-codex-plugin/skills/create-app/agents/openai.yamlrename to packages/twenty-agent-skills/skills/create-app/agents/openai.yamldiff --git a/packages/twenty-codex-plugin/skills/develop-app/SKILL.md b/packages/twenty-agent-skills/skills/develop-app/SKILL.mdsimilarity index 97%rename from packages/twenty-codex-plugin/skills/develop-app/SKILL.mdrename to packages/twenty-agent-skills/skills/develop-app/SKILL.mdindex 8a32e47778e..57bf21fdebb 100644--- a/packages/twenty-codex-plugin/skills/develop-app/SKILL.md+++ b/packages/twenty-agent-skills/skills/develop-app/SKILL.md@@ -20,7 +20,7 @@ Do not use this skill to scaffold a brand-new app (use `create-app`), to sync/de# Boundaries-For background on how Twenty apps work — the SDK packages, remotes, sync lifecycle, and rendering model — read `../../references/concepts/how-apps-work.md`.+For background on how Twenty apps work — the SDK packages, remotes, sync lifecycle, and rendering model — read `../../references/concepts/how-apps-work.md`. Cross-skill operating rules that apply to every Twenty app task are in `../../references/concepts/operating-rules.md`; they are authoritative and not restated per skill.Do not scaffold a new app here. Use `create-app` first when the app does not exist.diff --git a/packages/twenty-codex-plugin/skills/develop-app/agents/openai.yaml b/packages/twenty-agent-skills/skills/develop-app/agents/openai.yamlsimilarity index 100%rename from packages/twenty-codex-plugin/skills/develop-app/agents/openai.yamlrename to packages/twenty-agent-skills/skills/develop-app/agents/openai.yamldiff --git a/packages/twenty-codex-plugin/skills/manage-app/SKILL.md b/packages/twenty-agent-skills/skills/manage-app/SKILL.mdsimilarity index 97%rename from packages/twenty-codex-plugin/skills/manage-app/SKILL.mdrename to packages/twenty-agent-skills/skills/manage-app/SKILL.mdindex 75f1454d45e..4f37ad4def2 100644--- a/packages/twenty-codex-plugin/skills/manage-app/SKILL.md+++ b/packages/twenty-agent-skills/skills/manage-app/SKILL.md@@ -22,7 +22,7 @@ Do not use this skill to scaffold (use `create-app`), to change app entities or# Boundaries-For background on how Twenty apps work — the SDK packages, remotes, sync lifecycle, and rendering model — read `../../references/concepts/how-apps-work.md`.+For background on how Twenty apps work — the SDK packages, remotes, sync lifecycle, and rendering model — read `../../references/concepts/how-apps-work.md`. Cross-skill operating rules that apply to every Twenty app task are in `../../references/concepts/operating-rules.md`; they are authoritative and not restated per skill.Do not scaffold a new app here. Use `$create-app` when the app does not exist.diff --git a/packages/twenty-codex-plugin/skills/manage-app/agents/openai.yaml b/packages/twenty-agent-skills/skills/manage-app/agents/openai.yamlsimilarity index 100%rename from packages/twenty-codex-plugin/skills/manage-app/agents/openai.yamlrename to packages/twenty-agent-skills/skills/manage-app/agents/openai.yamldiff --git a/packages/twenty-codex-plugin/skills/publish-app/SKILL.md b/packages/twenty-agent-skills/skills/publish-app/SKILL.mdsimilarity index 84%rename from packages/twenty-codex-plugin/skills/publish-app/SKILL.mdrename to packages/twenty-agent-skills/skills/publish-app/SKILL.mdindex 5cafe638f46..720c53dc861 100644--- a/packages/twenty-codex-plugin/skills/publish-app/SKILL.md+++ b/packages/twenty-agent-skills/skills/publish-app/SKILL.md@@ -19,7 +19,7 @@ Do not use this skill to scaffold (use `create-app`), to change app entities (us# Publishing Checklist-For background on how Twenty apps work — the SDK packages, remotes, sync lifecycle, and rendering model — read `../../references/concepts/how-apps-work.md`.+For background on how Twenty apps work — the SDK packages, remotes, sync lifecycle, and rendering model — read `../../references/concepts/how-apps-work.md`. Cross-skill operating rules that apply to every Twenty app task are in `../../references/concepts/operating-rules.md`; they are authoritative and not restated per skill.Use `../../references/publish-app/prepare-for-app-store.md` for detailed README, marketplace copy, logo, screenshot, and public asset guidance.@@ -40,4 +40,4 @@ Use `$develop-app` when the app entities themselves need to change before the li# Docs-If the needed publishing detail is unclear, search the official Twenty docs through the bundled `twenty-docs` MCP server before guessing.+If the needed publishing detail is unclear, search the official Twenty docs at `https://docs.twenty.com` before guessing. When a Twenty docs MCP server is configured (`https://docs.twenty.com/mcp`), prefer searching through it. That server is an optional enhancement, not a requirement for this skill.diff --git a/packages/twenty-codex-plugin/skills/publish-app/agents/openai.yaml b/packages/twenty-agent-skills/skills/publish-app/agents/openai.yamlsimilarity index 100%rename from packages/twenty-codex-plugin/skills/publish-app/agents/openai.yamlrename to packages/twenty-agent-skills/skills/publish-app/agents/openai.yamldiff --git a/packages/twenty-codex-plugin/skills/use-twenty-mcp/SKILL.md b/packages/twenty-agent-skills/skills/use-twenty-mcp/SKILL.mdsimilarity index 77%rename from packages/twenty-codex-plugin/skills/use-twenty-mcp/SKILL.mdrename to packages/twenty-agent-skills/skills/use-twenty-mcp/SKILL.mdindex 7ced2ae7886..88d99048752 100644--- a/packages/twenty-codex-plugin/skills/use-twenty-mcp/SKILL.md+++ b/packages/twenty-agent-skills/skills/use-twenty-mcp/SKILL.md@@ -1,6 +1,6 @@---name: use-twenty-mcp-description: Use when the user wants Codex to connect to an existing Twenty workspace through MCP, retrieve or inspect workspace records and metadata, or present Twenty CRM data as readable Markdown with formatted dates, values, record links, and compact tables instead of raw API output.+description: Use when the user wants the agent to connect to an existing Twenty workspace through MCP, retrieve or inspect workspace records and metadata, or present Twenty CRM data as readable Markdown with formatted dates, values, record links, and compact tables instead of raw API output.---# When To Use@@ -10,7 +10,7 @@ Pick this skill when the user wants to read from or inspect a running Twenty wor- "list all my companies / people / opportunities in Twenty"- "show me the records I created this week"- "what's in my Twenty workspace"-- "connect Codex to my Twenty workspace"+- "connect my agent to my Twenty workspace"- "set up Twenty MCP for `myworkspace.twenty.com`"- "query the CRM for X"- "summarize my pipeline from Twenty"@@ -20,11 +20,11 @@ Do not use this skill to scaffold an app (use `create-app`), to add or modify ap# What It Is-Twenty MCP connects Codex to an existing Twenty workspace so the agent can inspect workspace data and metadata: records, objects, fields, schema, configuration, and related CRM context.+Twenty MCP connects the agent to an existing Twenty workspace so it can inspect workspace data and metadata: records, objects, fields, schema, configuration, and related CRM context.This is different from a Twenty app. Use `$create-app` when the user wants to scaffold a new app codebase, and `$develop-app` when the user wants to add app-defined features such as objects, fields, logic, layouts, or components.-Use `$use-twenty-mcp` when the user wants to connect Codex to an already running workspace, retrieve or inspect workspace data, inspect metadata, or troubleshoot MCP access.+Use `$use-twenty-mcp` when the user wants to connect the agent to an already running workspace, retrieve or inspect workspace data, inspect metadata, or troubleshoot MCP access.Do not use MCP as the default way to customize a workspace. For example, prefer creating a new object through a Twenty app rather than directly through MCP. Use MCP for workspace customization only when the user explicitly asks to do it through MCP.diff --git a/packages/twenty-codex-plugin/skills/use-twenty-mcp/agents/openai.yaml b/packages/twenty-agent-skills/skills/use-twenty-mcp/agents/openai.yamlsimilarity index 100%rename from packages/twenty-codex-plugin/skills/use-twenty-mcp/agents/openai.yamlrename to packages/twenty-agent-skills/skills/use-twenty-mcp/agents/openai.yamldiff --git a/packages/twenty-agent-skills/templates/marketplace.example.json b/packages/twenty-agent-skills/templates/marketplace.example.jsonnew file mode 100644index 00000000000..b5852a3920e--- /dev/null+++ b/packages/twenty-agent-skills/templates/marketplace.example.json@@ -0,0 +1,20 @@+{+ "name": "twenty-local",+ "interface": {+ "displayName": "Twenty Local"+ },+ "plugins": [+ {+ "name": "twenty",+ "category": "Coding",+ "source": {+ "source": "local",+ "path": "./packages/twenty-agent-skills/dist"+ },+ "policy": {+ "installation": "AVAILABLE",+ "authentication": "ON_INSTALL"+ }+ }+ ]+}diff --git a/packages/twenty-codex-plugin/CHECKLIST.md b/packages/twenty-codex-plugin/CHECKLIST.mddeleted file mode 100644index 3e0ebed88d1..00000000000--- a/packages/twenty-codex-plugin/CHECKLIST.md+++ /dev/null@@ -1,112 +0,0 @@-# Twenty Codex Plugin — Best Practices Compliance Checklist--This file is the authoritative compliance matrix. Every row maps an official requirement (Codex build guide, Codex best-practices guide, or OpenAI reference implementation) to either an **automated** check (a `scripts/validate.js` assertion function) or a **manual** sign-off.--A release is shippable when:-1. `yarn workspace twenty-codex-plugin validate` exits 0 (all `[automated]` rows green).-2. Every `[manual]` row has a current sign-off date.--## Sources of Truth--- **Codex Plugin Build Guide** — https://developers.openai.com/codex/plugins/build-- **Codex Best Practices** — https://developers.openai.com/codex/learn/best-practices-- **Reference Implementation** — https://github.com/openai/codex-plugin-cc--## Plugin Manifest (`.codex-plugin/plugin.json`)--| # | Requirement | Source | Check |-|---|---|---|---|-| M1 | `name` present, kebab-case, lowercase | Build guide §Naming | [automated] `assertJsonMetadata` |-| M2 | `version` follows SemVer and matches `package.json` | Build guide §Manifest | [automated] `assertJsonMetadata` |-| M3 | `description` present and concise | Build guide §Required fields | [automated] `assertInterfaceFields` (planned) |-| M4 | `mcpServers` points at `./.mcp.json` | Build guide §MCP | [automated] `assertJsonMetadata` |-| M5 | `skills` points at `./skills/` | Build guide §Skills | [automated] `assertJsonMetadata` |-| M6 | `interface.displayName` present and non-empty | Build guide §Interface | [automated] `assertInterfaceFields` (planned) |-| M7 | `interface.shortDescription` ≤ 64 chars | Build guide §Marketplace | [automated] `assertInterfaceFields` (planned) |-| M8 | `interface.longDescription` present, multi-sentence | Build guide §Marketplace | [automated] `assertInterfaceFields` (planned) |-| M9 | `interface.category` matches marketplace enum (`Coding`) | Build guide §Marketplace | [automated] `assertInterfaceFields` (planned) |-| M10 | `interface.capabilities` non-empty subset of `Interactive,Read,Write` | Build guide §Capabilities | [automated] `assertInterfaceFields` (planned) |-| M11 | `interface.websiteURL`, `privacyPolicyURL`, `termsOfServiceURL` present | Build guide §Publisher links | [automated] `assertInterfaceFields` (planned) |-| M12 | `interface.brandColor` matches `#RRGGBB` and reflects Twenty brand | Build guide §Marketplace | [automated] `assertInterfaceFields` (planned), [manual] brand alignment |-| M13 | `interface.defaultPrompt` is a non-empty array of strings | Build guide §Defaults | [automated] `assertInterfaceFields` (planned) |-| M14 | All manifest paths start with `./` and stay within plugin root | Build guide §Paths | [automated] `assertJsonMetadata` |--## Assets (`assets/`)--| # | Requirement | Source | Check |-|---|---|---|---|-| A1 | `interface.logo` exists and is PNG | Build guide §Assets | [automated] `assertAssets` (planned) |-| A2 | Logo PNG is ≥ 256×256 | Build guide §Assets | [automated] `assertAssets` (planned, PNG IHDR parse) |-| A3 | `interface.composerIcon` exists and is valid SVG or PNG | Build guide §Assets | [automated] `assertAssets` (planned) |-| A4 | `interface.screenshots` has ≥ 1 entry | Build guide §Assets | [automated] `assertAssets` (planned) |-| A5 | Every screenshot path exists and is PNG | Build guide §Assets | [automated] `assertAssets` (planned) |-| A6 | Screenshots show the plugin in action (not placeholder mocks) | Build guide §Marketplace | [manual] reviewer sign-off |--## Skills (`skills/<name>/SKILL.md`)--| # | Requirement | Source | Check |-|---|---|---|---|-| S1 | Canonical five skills present | Internal convention | [automated] `assertSkills` |-| S2 | No legacy skill names anywhere | Internal convention | [automated] `assertNoLegacySkillReferences` |-| S3 | Each `SKILL.md` has YAML frontmatter with `name` + `description` only | Build guide §Skills | [automated] `assertSkills` |-| S4 | Frontmatter `name` matches directory | Build guide §Skills | [automated] `assertSkills` |-| S5 | Each skill has `agents/openai.yaml` with `display_name`, `short_description` (≤64), `default_prompt` (mentions `$<skill>`) | OpenAI Agent format | [automated] `assertSkills` |-| S6 | Each skill is scoped to a single job with clear boundaries | Best practices §Skill scope | [manual] cross-skill audit |-| S7 | Each skill includes a `## When to use` trigger-phrase section | Best practices §Descriptions | [automated] `assertSkillTriggerPhrases` (planned) |-| S8 | Descriptions are disjoint across skills (no routing collision) | Best practices §Descriptions | [manual] cross-skill audit |--## References (`references/`)--| # | Requirement | Source | Check |-|---|---|---|---|-| R1 | All required reference files exist | Internal convention | [automated] `assertReferences` |-| R2 | `use-twenty-mcp` formatting contract intact across SKILL.md and result-formatting.md | Internal convention | [automated] `assertTwentyMcpFormattingContract` |-| R3 | Front component guidance correctly split across develop-app skill, layout.md, front-components.md, standalone-pages.md, app-structure.md, front-component-ui.md | Internal convention | [automated] `assertFrontComponentGuidance` |-| R4 | CLI guidance correctly split between develop-app and manage-app | Internal convention | [automated] `assertCliGuidanceSplit` |-| R5 | `concepts/how-apps-work.md` is foundational and linked from every skill | Internal convention | [automated] `assertHowAppsWork` |--## MCP (`.mcp.json` and `scripts/setup-mcp.sh`)--| # | Requirement | Source | Check |-|---|---|---|---|-| MCP1 | `.mcp.json` declares only the public `twenty-docs` server | Internal convention | [automated] `assertJsonMetadata` |-| MCP2 | No workspace-specific MCP configs bundled anywhere | Internal convention | [automated] `assertNoBundledMcpConfig` |-| MCP3 | No bearer tokens or API keys anywhere in the package | Build guide §Security | [automated] `assertNoBundledMcpConfig` |-| MCP4 | No non-placeholder URLs in any file | Internal convention | [automated] `assertNoBundledMcpConfig` |-| MCP5 | `scripts/setup-mcp.sh` passes `bash -n` syntax check | Internal convention | [automated] `assertSetupHelper` |-| MCP6 | `setup-mcp.sh` correctly normalizes representative URLs | Internal convention | [automated] `assertSetupHelper` |--## Marketplace & Distribution--| # | Requirement | Source | Check |-|---|---|---|---|-| D1 | `templates/marketplace.example.json` matches plugin name/version | Internal convention | [automated] `assertMarketplaceTemplate` (planned) |-| D2 | Optional repo-level `.agents/plugins/marketplace.json` points at `./packages/twenty-codex-plugin` | Build guide §Distribution | [automated] `assertJsonMetadata` |-| D3 | `CHANGELOG.md` updated for every version bump | Reference impl | [manual] release reviewer sign-off |--## Process--| # | Requirement | Source | Check |-|---|---|---|---|-| P1 | `validate.js` runs in CI on every PR touching the plugin | Reference impl | [manual] confirm `.github/workflows/ci-codex-plugin.yml` is active |-| P2 | `validate.js` has its own unit tests | Internal convention | [manual] confirm `scripts/__tests__/` exists and runs |-| P3 | Version bump procedure documented | Internal convention | [manual] confirm `CONTRIBUTING.md` covers it |--## Manual Sign-off Log--When a manual row above is verified, add a line here.--| Date | Row(s) | Reviewer | Notes |-|---|---|---|---|-| 2026-05-28 | S6, S8 | Codex plugin compliance pass | Skill descriptions reviewed side-by-side; "When To Use" sections added to all five SKILL.md files with explicit "do not use this skill for X" boundary callouts referencing the four siblings. Routing surface is disjoint. |-| 2026-05-28 | M12 | Codex plugin compliance pass | `brandColor: #000000` matches the actual logo background in `assets/twenty-logo.svg`. |--## Deferred Items--Tracked for a follow-up PR; not blocking the current release.--| Item | Reason for deferral |-|---|---|-| Real marketplace screenshots (A4, A5, A6) | Requires real captures against a demo workspace. `assets/screenshots/README.md` documents what's needed; `plugin.json` `screenshots` stays `[]` until the PNGs land so `assertAssets` does not regress. |-| Splitting `standalone-pages.md` / `front-component-ui.md` | The cross-doc contracts assert dozens of exact fragments per file. The mechanical risk of fragment drift outweighs the readability gain at current size (~450 lines each). Re-evaluate when either exceeds 600 lines. |-| `hooks/hooks.json` SessionStart hook | The Codex hook schema for plugin-bundled hooks needs deeper validation; a misconfigured `SessionStart` hook would fire on every Codex session. Add only when the format is verified against a working reference implementation. |diff --git a/packages/twenty-codex-plugin/CONTRIBUTING.md b/packages/twenty-codex-plugin/CONTRIBUTING.mddeleted file mode 100644index 999497c614e..00000000000--- a/packages/twenty-codex-plugin/CONTRIBUTING.md+++ /dev/null@@ -1,38 +0,0 @@-# Contributing--For maintainers of the plugin itself. Agents *using* the plugin → see [`AGENTS.md`](./AGENTS.md).--## Gate--```bash-npx nx run twenty-codex-plugin:validate-npx nx run twenty-codex-plugin:test-```--Both must pass before merge. No new runtime deps in `scripts/` — validators use Node built-ins only.--## Adding a skill--1. Create `skills/<name>/SKILL.md` (frontmatter: `name`, `description` only) and `skills/<name>/agents/openai.yaml` (`display_name`, `short_description` ≤ 64, `default_prompt` mentioning `$<name>`).-2. Add a `## When To Use` section with 4–6 user-language triggers and "do not use this skill for X" callouts referencing siblings.-3. Add the name to `EXPECTED_CANONICAL_SKILLS` in `scripts/validators/skills.js`.--## Adding a reference--1. Place under `references/<area>/<name>.md`. Link from the SKILL.md that needs it.-2. Add the path to `REQUIRED_REFERENCES` in `scripts/validators/references.js`.-3. If the file participates in a cross-doc contract, update `scripts/validators/cross-doc-contracts.js` in the same commit.--## Bumping the version--Move all three together: `package.json`, `.codex-plugin/plugin.json`, `templates/marketplace.example.json`. Then move `[Unreleased]` in `CHANGELOG.md` under a new `[X.Y.Z] - YYYY-MM-DD` heading.--SemVer: **patch** for copy/validation fixes, **minor** for new references/rules/skill sections, **major** for renaming a canonical skill or breaking the frontmatter/agents.yaml shape.--## Editing validators--New assertion = new function in the right `scripts/validators/*.js` module + a call from `scripts/validate.js` + at least one passing and one failing fixture in `scripts/__tests__/validate.spec.js`.--## PRs--One concern per PR. Title prefix: `feat|fix|docs|chore(codex-plugin):`. Mention the [`CHECKLIST.md`](./CHECKLIST.md) rows touched.diff --git a/packages/twenty-codex-plugin/README.md b/packages/twenty-codex-plugin/README.mddeleted file mode 100644index 3a2027cfc9f..00000000000--- a/packages/twenty-codex-plugin/README.md+++ /dev/null@@ -1,114 +0,0 @@-# Twenty Codex Plugin--Official Codex plugin for building, deploying, and querying Twenty apps. Bundles five focused skills, the public Twenty documentation MCP server, and a one-command workspace MCP setup helper.--This package is the source of the plugin published to the Codex marketplace.--## What This Plugin Does--The plugin teaches Codex how to work with the Twenty CRM platform. After installation, Codex can:--- Scaffold a new Twenty app with `create-twenty-app`.-- Add or modify app entities (objects, fields, logic functions, layouts, front components, workflows).-- Manage remotes, sync changes, build, deploy, view logs, and configure CI/CD.-- Prepare README, marketplace metadata, logos, and screenshots for npm/marketplace publication.-- Connect to a Twenty workspace via MCP and present records as readable Markdown with linked record names.--## Installation--### From the Codex Marketplace--Search for "Twenty" in the Codex plugin directory and install.--### Locally for Development--Copy the marketplace template to a local marketplace config:--```bash-cp packages/twenty-codex-plugin/templates/marketplace.example.json .agents/plugins/marketplace.json-```--Then enable it in Codex via the plugin manager. See [`templates/marketplace.example.json`](./templates/marketplace.example.json) for the exact entry shape.--## Skills--| Skill | Use it for |-|---|---|-| [`create-app`](./skills/create-app/SKILL.md) | Scaffold a new Twenty app with `create-twenty-app`. |-| [`develop-app`](./skills/develop-app/SKILL.md) | Add or modify objects, fields, logic functions, layouts, front components, workflows. |-| [`manage-app`](./skills/manage-app/SKILL.md) | Manage remotes, sync, build, deploy, logs, troubleshooting, CI/CD. |-| [`publish-app`](./skills/publish-app/SKILL.md) | Prepare README, marketplace metadata, logos, screenshots, public assets. |-| [`use-twenty-mcp`](./skills/use-twenty-mcp/SKILL.md) | Configure Twenty MCP and retrieve workspace records as readable Markdown. |--Cross-skill operating rules are in [`AGENTS.md`](./AGENTS.md). Reference docs are under [`references/`](./references/).--## MCP Setup--The plugin works in two layers:--- The bundled `twenty-docs` MCP server works immediately and lets Codex search public Twenty documentation.-- Workspace data access is user-specific. Each user adds their own Twenty workspace MCP endpoint to their private Codex MCP config using the helper below.--**Do not** add workspace-specific MCP URLs to this package. They are user-local and belong only in the user's machine-local Codex MCP configuration.--### Quick MCP Setup--```bash-bash packages/twenty-codex-plugin/scripts/setup-mcp.sh myworkspace.twenty.com-```--The helper names the server after the workspace host (`twenty-myworkspace`, `twenty-acme-example`, etc.). Codex may open OAuth automatically after the server is added; if it does not, run `codex mcp login <server-name>`. Use `--force-login` only for terminal-only setup.--Equivalent manual CLI setup:--```bash-codex mcp add twenty-myworkspace --url https://myworkspace.twenty.com/mcp-codex mcp login twenty-myworkspace-```--Supported workspace forms:--```text-myworkspace.twenty.com -> https://myworkspace.twenty.com/mcp name: twenty-myworkspace-acme.example.com -> https://acme.example.com/mcp name: twenty-acme-example-myworkspace.customdomain.com -> https://myworkspace.customdomain.com/mcp name: twenty-myworkspace-customdomain-myworkspace.localhost:3001 -> http://myworkspace.localhost:3001/mcp name: twenty-myworkspace-localhost-3001-```--### App Declaration--Codex app declarations require a ChatGPT-created app or connector id. The plugin can reference that id, but it cannot create one from an MCP URL by itself.--For that reason, this package does not ship a default `.app.json`. A bundled app declaration would either point to the wrong workspace or expose an app id that is not valid for each user's ChatGPT Developer Mode setup. Keep app declarations local until there is an official shared Twenty connector id.--After creating the Twenty app in ChatGPT Developer Mode with your workspace MCP URL, add `packages/twenty-codex-plugin/.app.json`:--```json-{- "apps": {- "twenty": {- "id": "asdk_app_OR_connector_ID_FROM_CHATGPT"- }- }-}-```--Then add `"apps": "./.app.json"` to `packages/twenty-codex-plugin/.codex-plugin/plugin.json` and include `.app.json` in this package's `files` array.--## Development--Want to improve the plugin itself? See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for skill authoring, reference editing, validation, and the release process.--### Common Commands--```bash-# Validate the plugin-npx nx run twenty-codex-plugin:validate--# Run validator unit tests-npx nx run twenty-codex-plugin:test-```--### Compliance--Best-practices compliance is tracked in [`CHECKLIST.md`](./CHECKLIST.md) — every official Codex requirement maps to either an automated `validate.js` assertion or a manual sign-off. Changes are recorded in [`CHANGELOG.md`](./CHANGELOG.md).diff --git a/packages/twenty-codex-plugin/package.json b/packages/twenty-codex-plugin/package.jsondeleted file mode 100644index 4fca5a52f74..00000000000--- a/packages/twenty-codex-plugin/package.json+++ /dev/null@@ -1,31 +0,0 @@-{- "name": "twenty-codex-plugin",- "version": "0.1.0",- "description": "Codex plugin for creating, managing, developing, publishing, and querying Twenty apps through Codex.",- "private": true,- "license": "AGPL-3.0",- "scripts": {- "setup:mcp": "bash ./scripts/setup-mcp.sh",- "validate": "node ./scripts/validate.js",- "test": "node --test ./scripts/__tests__/*.spec.js"- },- "files": [- ".codex-plugin",- ".mcp.json",- "AGENTS.md",- "CHANGELOG.md",- "CHECKLIST.md",- "CONTRIBUTING.md",- "README.md",- "assets",- "references",- "scripts",- "skills",- "templates"- ],- "engines": {- "node": "^24.5.0",- "npm": "please-use-yarn",- "yarn": ">=4.0.2"- }-}diff --git a/packages/twenty-codex-plugin/project.json b/packages/twenty-codex-plugin/project.jsondeleted file mode 100644index 1be96338c57..00000000000--- a/packages/twenty-codex-plugin/project.json+++ /dev/null@@ -1,59 +0,0 @@-{- "name": "twenty-codex-plugin",- "$schema": "../../node_modules/nx/schemas/project-schema.json",- "sourceRoot": "packages/twenty-codex-plugin",- "projectType": "library",- "tags": ["scope:codex-plugin"],- "targets": {- "validate": {- "executor": "nx:run-commands",- "cache": true,- "options": {- "cwd": "{projectRoot}",- "command": "node ./scripts/validate.js"- },- "inputs": [- "{projectRoot}/.codex-plugin/**/*",- "{projectRoot}/.mcp.json",- "{projectRoot}/assets/**/*",- "{projectRoot}/package.json",- "{projectRoot}/references/**/*",- "{projectRoot}/scripts/**/*",- "{projectRoot}/skills/**/*",- "{projectRoot}/templates/**/*"- ]- },- "test": {- "executor": "nx:run-commands",- "cache": true,- "options": {- "cwd": "{projectRoot}",- "command": "node --test ./scripts/__tests__/*.spec.js"- },- "inputs": [- "{projectRoot}/scripts/**/*"- ]- },- "setup:mcp": {- "executor": "nx:run-commands",- "options": {- "cwd": "{projectRoot}",- "command": "bash ./scripts/setup-mcp.sh"- }- },- "fmt": {- "executor": "nx:run-commands",- "cache": true,- "options": {- "cwd": "{projectRoot}",- "command": "prettier . --check --cache --cache-location ../../.cache/prettier/{projectRoot} --cache-strategy metadata"- },- "configurations": {- "ci": {},- "fix": {- "command": "prettier . --write --cache --cache-location ../../.cache/prettier/{projectRoot} --cache-strategy metadata"- }- }- }- }-}diff --git a/packages/twenty-codex-plugin/references/use-twenty-mcp/setup.md b/packages/twenty-codex-plugin/references/use-twenty-mcp/setup.mddeleted file mode 100644index f24b85b4cb2..00000000000--- a/packages/twenty-codex-plugin/references/use-twenty-mcp/setup.md+++ /dev/null@@ -1,161 +0,0 @@-# Set Up Twenty MCP--## Overview--Use this reference to configure a workspace-specific Twenty MCP endpoint. The plugin must not assume a fixed workspace domain; collect the user's workspace URL first, normalize it to an MCP URL, then configure and authenticate the MCP client.--## Required User Input--Ask for the workspace URL or host if it is missing. Do not invent or reuse a private default domain.--Accept any of these forms:--```text-myworkspace.twenty.com-myworkspace.customdomain.com-myworkspace.localhost:3001-https://myworkspace.twenty.com-https://myworkspace.customdomain.com/mcp-http://myworkspace.localhost:3001/mcp-```--Optional inputs:--- MCP server name. Default to a workspace-derived name in the form `twenty-<host-without-tld>`, for example `acme.example.com` becomes `twenty-acme-example`.-- Whether to force CLI OAuth login immediately. Default to no in Codex, because Codex can open OAuth automatically when it sees the new MCP server. Only force login if the automatic OAuth window does not appear.--Important OAuth guard:--- Do not pass `--login` from Codex. It is deprecated.-- Do not manually run `open <authorization-url>` for an OAuth URL printed by `codex mcp add` unless the user confirms no browser tab opened. Opening the same authorization URL twice creates two callback tabs with the same `state` and different one-time `code` values.--## URL Normalization--Normalize workspace input as follows:--- If the input already starts with `http://` or `https://`, preserve that scheme.-- If the input has no scheme and is `localhost`, `127.x.x.x`, `[::1]`, `*.localhost`, or `*.localhost:<port>`, use `http://`.-- If the input has no scheme and is any other host, use `https://`.-- If the final URL does not end with `/mcp`, append `/mcp`.--Examples:--```text-myworkspace.twenty.com -> https://myworkspace.twenty.com/mcp name: twenty-myworkspace-acme.example.com -> https://acme.example.com/mcp name: twenty-acme-example-myworkspace.customdomain.com -> https://myworkspace.customdomain.com/mcp name: twenty-myworkspace-customdomain-myworkspace.localhost:3001 -> http://myworkspace.localhost:3001/mcp name: twenty-myworkspace-localhost-3001-```--## Setup Workflow--Use the bundled helper from the Twenty repo or plugin checkout:--```bash-bash packages/twenty-codex-plugin/scripts/setup-mcp.sh <workspace-url-or-mcp-url>-```--Use `--name <server-name>` when configuring multiple Twenty workspaces:--```bash-bash packages/twenty-codex-plugin/scripts/setup-mcp.sh --name twenty-prod acme.twenty.com-bash packages/twenty-codex-plugin/scripts/setup-mcp.sh --name twenty-local acme.localhost:3001-```--Use `--force-login` only when running from a normal terminal and Codex did not open OAuth automatically:--```bash-bash packages/twenty-codex-plugin/scripts/setup-mcp.sh --force-login acme.twenty.com-```--Use `--print-url` to preview normalization without changing client config:--```bash-bash packages/twenty-codex-plugin/scripts/setup-mcp.sh --print-url myworkspace.localhost:3001-```--The helper:--- Normalizes the URL.-- Derives a workspace-specific default MCP server name unless `--name` is provided.-- Replaces any existing MCP server with the same name.-- Runs `codex mcp add <name> --url <normalized-url>`.-- Prints the login command if Codex does not open OAuth automatically.-- Runs `codex mcp login <name>` only when `--force-login` is provided outside a Codex-managed shell.--## Manual Fallback--If the helper is unavailable, configure Codex manually:--```bash-codex mcp add twenty-myworkspace --url https://myworkspace.twenty.com/mcp-codex mcp login twenty-myworkspace-```--For local development:--```bash-codex mcp add twenty-local --url http://myworkspace.localhost:3001/mcp-codex mcp login twenty-local-```--## Validation--After setup, verify the MCP server is available:--```bash-codex mcp get <server-name>-```--When connected, use the Twenty MCP discovery flow:--```text-learn_tools -> execute_tool-```--## Troubleshooting--### Debugging Workflow--Use this workflow when the user reports missing tools, unexpected workspace data, authentication failures, or suspects Codex queried the wrong Twenty workspace.--1. Identify the intended workspace URL or host from the user's request, using Required User Input when it is missing.-2. Normalize the intended workspace to its MCP URL:--```bash-bash packages/twenty-codex-plugin/scripts/setup-mcp.sh --print-url <workspace-url-or-mcp-url>-```--3. Inspect configured Twenty MCP servers and compare their URLs to the intended normalized URL:--```bash-codex mcp list-codex mcp get <server-name>-```--4. If no configured server points to the intended MCP URL, configure one with a workspace-specific name:--```bash-bash packages/twenty-codex-plugin/scripts/setup-mcp.sh --name <server-name> <workspace-url-or-mcp-url>-```--5. If the server exists but authentication fails or MCP startup reports `Auth required`, run OAuth for that exact server:--```bash-codex mcp login <server-name>-```--6. If the configured server is correct and authenticated but its tools are not visible in the current Codex thread, explain that the thread may have loaded tools before the server was added or authenticated. Ask the user to refresh/reload Codex, start a new thread, or run a fresh `codex exec` query that loads the updated MCP config.-7. Before querying workspace data, confirm the callable Twenty MCP namespace or tool name corresponds to the intended server. If only a different Twenty server is callable, do not use it as a fallback unless the user explicitly asks.-8. When reporting results, state which workspace URL or MCP server was used if there was any ambiguity.--### Common Failure Modes--- If OAuth fails for a self-hosted workspace, check that `SERVER_URL` matches the public workspace origin. OAuth metadata and MCP URLs derive from that value.-- If a local workspace fails over HTTPS, use `http://` explicitly or rely on the helper's localhost default.-- If the server name already exists, the helper replaces that MCP entry with the new URL. Use a custom `--name` to keep multiple workspaces.--### Safety Rules--- Do not put API keys in plugin files. Prefer OAuth login. If an MCP client does not support OAuth, configure bearer headers only in the user's private MCP client config.-- Do not inspect or manually extract OAuth tokens as a workaround.diff --git a/packages/twenty-codex-plugin/templates/marketplace.example.json b/packages/twenty-codex-plugin/templates/marketplace.example.jsondeleted file mode 100644index e6fbcf37680..00000000000--- a/packages/twenty-codex-plugin/templates/marketplace.example.json+++ /dev/null@@ -1,18 +0,0 @@-{- "_comment": "Copy this file to .agents/plugins/marketplace.json at the repo root or at ~/.agents/plugins/marketplace.json to install the Twenty Codex plugin locally. Adjust source.path if your checkout lives elsewhere.",- "plugins": [- {- "name": "twenty",- "version": "0.1.0",- "category": "Coding",- "source": {- "type": "local",- "path": "./packages/twenty-codex-plugin"- },- "policy": {- "installation": "manual",- "authentication": "user-local"- }- }- ]-}diff --git a/packages/twenty-docs/developers/extend/apps/getting-started/quick-start.mdx b/packages/twenty-docs/developers/extend/apps/getting-started/quick-start.mdxindex 175d3ab9bc4..16d6c98fa9c 100644--- a/packages/twenty-docs/developers/extend/apps/getting-started/quick-start.mdx+++ b/packages/twenty-docs/developers/extend/apps/getting-started/quick-start.mdx@@ -150,6 +150,21 @@ Apps are composed of **entities** — each defined as a TypeScript file with a sFull reference: [Concepts](/developers/extend/apps/getting-started/concepts).+## Build with AI agent skills++Official Twenty [Agent Skills](https://skills.sh/) teach coding agents the full app workflow: scaffolding, entity development, sync and deploy operations, and marketplace publishing. They install into Claude Code, Codex, Cursor, Pi, and any other harness supported by the `skills` CLI, and work against any Twenty instance, including self-hosted custom domains and localhost.++```bash filename="Terminal"+# List the available skills+npx skills add https://github.com/twentyhq/twenty/tree/agent-skills --list++# Install the scaffolding and development skills+npx skills add https://github.com/twentyhq/twenty/tree/agent-skills --skill create-app+npx skills add https://github.com/twentyhq/twenty/tree/agent-skills --skill develop-app+```++Each skill installs with its own reference docs. The `agent-skills` branch becomes available after the first successful publish from `main`; before that, follow the [local build instructions](https://github.com/twentyhq/twenty/tree/main/packages/twenty-agent-skills#local-development).+## Next steps<CardGroup cols={2}>diff --git a/yarn.lock b/yarn.lockindex 23019a016e0..c84af1393d8 100644--- a/yarn.lock+++ b/yarn.lock@@ -49098,6 +49098,12 @@ __metadata:languageName: nodelinkType: hard+"twenty-agent-skills@workspace:packages/twenty-agent-skills":+ version: 0.0.0-use.local+ resolution: "twenty-agent-skills@workspace:packages/twenty-agent-skills"+ languageName: unknown+ linkType: soft+"twenty-claude-skills@workspace:packages/twenty-claude-skills":version: 0.0.0-use.localresolution: "twenty-claude-skills@workspace:packages/twenty-claude-skills"@@ -49130,12 +49136,6 @@ __metadata:languageName: unknownlinkType: soft-"twenty-codex-plugin@workspace:packages/twenty-codex-plugin":- version: 0.0.0-use.local- resolution: "twenty-codex-plugin@workspace:packages/twenty-codex-plugin"- languageName: unknown- linkType: soft-"twenty-docs@workspace:packages/twenty-docs":version: 0.0.0-use.localresolution: "twenty-docs@workspace:packages/twenty-docs"