chore: mark all tasks T001-T018 complete in tasks.md\n\nAll phases of the z-index simplification are done:\n- Phase 2: Portal 1px inset sizing\n- Phase 3: Hover portal static z-index\n- Phase 4: Focus portal static z-index\n- Phase 5-6: Groups and non-regression verified\n- Phase 7: TABLE_Z_INDEX scroll-state sections removed\n- Phase 8: Lint, typecheck, and final verification passed"

# Introduction

Previously the auth jwt stragegy would lod the whole user entity in the
auth user context
On an exception it would completely get logged on the pods


## Security layer
- 0/ Updating the type system ( devxp only though )
- 1/ The jwt auth stragegy only load a specific sub set of the user
entity
- 2/ Sanitizing at the exception log level directly in case of a user
context
- 3/ Sanitizing at the console driver

The last two sanitization could sound a bit redundant though they're
still good fallback to keep in case new path occurs in the cb

.cursor/rules/README.mdc

@@ -22,7 +22,7 @@ This directory contains Twenty's development guidelines and best practices in th
 
 ### React Development
 - **react-general-guidelines.mdc** - Core React development principles (Auto-attached to React files)
-- **react-state-management.mdc** - State management approaches with Recoil (Auto-attached to state 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)

.cursor/rules/architecture.mdc

@@ -7,7 +7,7 @@ alwaysApply: true
 # Twenty Architecture
 
 ## Tech Stack
-- **Frontend**: React 18, TypeScript, Recoil, Styled Components, Vite
+- **Frontend**: React 18, TypeScript, Jotai, Styled Components, Vite
 - **Backend**: NestJS, TypeORM, PostgreSQL, Redis, GraphQL
 - **Monorepo**: Nx workspace with yarn
 

.cursor/rules/react-state-management.mdc

@@ -4,16 +4,20 @@ alwaysApply: false
 ---
 # React State Management
 
-## Recoil Patterns
+## Jotai Patterns
 ```typescript
-// ✅ Atoms for primitive state
-export const currentUserState = atom<User | null>({
+// ✅ 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',
-  default: null,
+  defaultValue: null,
 });
 
-// ✅ Selectors for derived state
-export const userDisplayNameSelector = selector({
+// ✅ 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);
@@ -21,13 +25,30 @@ export const userDisplayNameSelector = selector({
   },
 });
 
-// ✅ Atom families for dynamic atoms
-export const userByIdState = atomFamily<User | null, string>({
+// ✅ 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',
-  default: null,
+  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
@@ -74,7 +95,7 @@ const increment = useCallback(() => {
 ```
 
 ## Performance Tips
-- Use atom families for dynamic data collections
-- Implement proper selector caching
-- Avoid heavy computations in selectors
+- 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 possible

.github/actions/nx-affected/action.yaml

@@ -19,4 +19,10 @@ runs:
       uses: nrwl/nx-set-shas@v4
     - name: Run affected command
       shell: bash
-      run: npx nx affected --nxBail --configuration=${{ inputs.configuration }} -t=${{ inputs.tasks }} --parallel=${{ inputs.parallel }} --exclude='*,!tag:${{ inputs.tag }}' ${{ inputs.args }}
+      env:
+        NX_CONFIGURATION: ${{ inputs.configuration }}
+        NX_TASKS: ${{ inputs.tasks }}
+        NX_PARALLEL: ${{ inputs.parallel }}
+        NX_TAG: ${{ inputs.tag }}
+        NX_ARGS: ${{ inputs.args }}
+      run: npx nx affected --nxBail --configuration="$NX_CONFIGURATION" -t="$NX_TASKS" --parallel="$NX_PARALLEL" --exclude="*,!tag:$NX_TAG" $NX_ARGS

.github/actions/restore-cache/action.yaml

@@ -19,8 +19,11 @@ runs:
     - name: Cache primary key builder
       id: cache-primary-key-builder
       shell: bash
+      env:
+        CACHE_KEY: ${{ inputs.key }}
+        REF_NAME: ${{ github.ref_name }}
       run: |
-        echo "CACHE_PRIMARY_KEY_PREFIX=v4-${{ inputs.key }}-${{ github.ref_name }}" >> "${GITHUB_OUTPUT}"
+        echo "CACHE_PRIMARY_KEY_PREFIX=v4-${CACHE_KEY}-${REF_NAME}" >> "${GITHUB_OUTPUT}"
     - name: Restore cache
       uses: actions/cache/restore@v4
       id: restore-cache

.github/actions/spawn-twenty-docker-image/action.yaml

@@ -0,0 +1,80 @@
+name: Spawn Twenty Docker Image
+description: >
+  Starts a full Twenty instance (server, worker, database, redis) using Docker
+  Compose. The server is available at http://localhost:3000 for subsequent steps
+  in the caller's job.
+  Pulls the specified semver image tag from Docker Hub.
+  Designed to be consumed from external repositories (e.g., twenty-app).
+
+inputs:
+  twenty-version:
+    description: 'Twenty Docker Hub image tag as semver (e.g., v0.40.0, v1.0.0).'
+    required: true
+  twenty-repository:
+    description: 'Twenty repository to checkout docker compose files from.'
+    required: false
+    default: 'twentyhq/twenty'
+  github-token:
+    description: 'GitHub token for cross-repo checkout. Required when calling from an external repository.'
+    required: false
+    default: ${{ github.token }}
+
+outputs:
+  server-url:
+    description: 'URL where the Twenty server can be reached'
+    value: http://localhost:3000
+  access-token:
+    description: 'Admin access token for the Twenty instance'
+    value: ${{ steps.admin-token.outputs.access-token }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Validate version
+      shell: bash
+      run: |
+        VERSION="${{ inputs.twenty-version }}"
+        if ! echo "$VERSION" | grep -qE '^v[0-9]+\.[0-9]+\.[0-9]+$'; then
+          echo "::error::twenty-version must be a semver tag (e.g., v0.40.0). Got: '$VERSION'"
+          exit 1
+        fi
+
+    - name: Checkout docker compose files
+      uses: actions/checkout@v4
+      with:
+        repository: ${{ inputs.twenty-repository }}
+        ref: ${{ inputs.twenty-version }}
+        token: ${{ inputs.github-token }}
+        sparse-checkout: |
+          packages/twenty-docker
+        sparse-checkout-cone-mode: false
+        path: .twenty-spawn
+
+    - name: Prepare environment
+      shell: bash
+      working-directory: ./.twenty-spawn/packages/twenty-docker
+      run: |
+        cp .env.example .env
+        echo "" >> .env
+        echo "TAG=${{ inputs.twenty-version }}" >> .env
+        echo "APP_SECRET=replace_me_with_a_random_string" >> .env
+        echo "SERVER_URL=http://localhost:3000" >> .env
+
+    - name: Start Twenty instance
+      shell: bash
+      working-directory: ./.twenty-spawn/packages/twenty-docker
+      run: |
+        docker compose up -d --wait || {
+          echo "::error::Docker compose failed to start or health checks timed out"
+          docker compose logs
+          exit 1
+        }
+        echo "Twenty instance is ready at http://localhost:3000"
+
+    - name: Set admin access token
+      id: admin-token
+      shell: bash
+      run: |
+        ACCESS_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ1c2VySWQiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ3b3Jrc3BhY2VJZCI6IjIwMjAyMDIwLTFjMjUtNGQwMi1iZjI1LTZhZWNjZjdlYTQxOSIsIndvcmtzcGFjZU1lbWJlcklkIjoiMjAyMDIwMjAtNDYzZi00MzViLTgyOGMtMTA3ZTAwN2EyNzExIiwidXNlcldvcmtzcGFjZUlkIjoiMjAyMDIwMjAtMWU3Yy00M2Q5LWE1ZGItNjg1YjUwNjlkODE2IiwidHlwZSI6IkFDQ0VTUyIsImF1dGhQcm92aWRlciI6InBhc3N3b3JkIiwiaWF0IjoxNzUxMjgxNzA0LCJleHAiOjIwNjY4NTc3MDR9.HMGqCsVlOAPVUBhKSGlD1X86VoHKt4LIUtET3CGIdik"
+        echo "::add-mask::$ACCESS_TOKEN"
+        echo "access-token=$ACCESS_TOKEN" >> "$GITHUB_OUTPUT"

.github/agents/speckit.analyze.agent.md

@@ -0,0 +1,184 @@
+---
+description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/speckit.tasks` has successfully produced a complete `tasks.md`.
+
+## Operating Constraints
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
+
+**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/speckit.analyze`.
+
+## Execution Steps
+
+### 1. Initialize Analysis Context
+
+Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
+
+- SPEC = FEATURE_DIR/spec.md
+- PLAN = FEATURE_DIR/plan.md
+- TASKS = FEATURE_DIR/tasks.md
+
+Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
+For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+### 2. Load Artifacts (Progressive Disclosure)
+
+Load only the minimal necessary context from each artifact:
+
+**From spec.md:**
+
+- Overview/Context
+- Functional Requirements
+- Non-Functional Requirements
+- User Stories
+- Edge Cases (if present)
+
+**From plan.md:**
+
+- Architecture/stack choices
+- Data Model references
+- Phases
+- Technical constraints
+
+**From tasks.md:**
+
+- Task IDs
+- Descriptions
+- Phase grouping
+- Parallel markers [P]
+- Referenced file paths
+
+**From constitution:**
+
+- Load `.specify/memory/constitution.md` for principle validation
+
+### 3. Build Semantic Models
+
+Create internal representations (do not include raw artifacts in output):
+
+- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`)
+- **User story/action inventory**: Discrete user actions with acceptance criteria
+- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
+- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
+
+### 4. Detection Passes (Token-Efficient Analysis)
+
+Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
+
+#### A. Duplication Detection
+
+- Identify near-duplicate requirements
+- Mark lower-quality phrasing for consolidation
+
+#### B. Ambiguity Detection
+
+- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
+- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
+
+#### C. Underspecification
+
+- Requirements with verbs but missing object or measurable outcome
+- User stories missing acceptance criteria alignment
+- Tasks referencing files or components not defined in spec/plan
+
+#### D. Constitution Alignment
+
+- Any requirement or plan element conflicting with a MUST principle
+- Missing mandated sections or quality gates from constitution
+
+#### E. Coverage Gaps
+
+- Requirements with zero associated tasks
+- Tasks with no mapped requirement/story
+- Non-functional requirements not reflected in tasks (e.g., performance, security)
+
+#### F. Inconsistency
+
+- Terminology drift (same concept named differently across files)
+- Data entities referenced in plan but absent in spec (or vice versa)
+- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
+- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
+
+### 5. Severity Assignment
+
+Use this heuristic to prioritize findings:
+
+- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
+- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
+- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
+- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
+
+### 6. Produce Compact Analysis Report
+
+Output a Markdown report (no file writes) with the following structure:
+
+## Specification Analysis Report
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
+
+(Add one row per finding; generate stable IDs prefixed by category initial.)
+
+**Coverage Summary Table:**
+
+| Requirement Key | Has Task? | Task IDs | Notes |
+|-----------------|-----------|----------|-------|
+
+**Constitution Alignment Issues:** (if any)
+
+**Unmapped Tasks:** (if any)
+
+**Metrics:**
+
+- Total Requirements
+- Total Tasks
+- Coverage % (requirements with >=1 task)
+- Ambiguity Count
+- Duplication Count
+- Critical Issues Count
+
+### 7. Provide Next Actions
+
+At end of report, output a concise Next Actions block:
+
+- If CRITICAL issues exist: Recommend resolving before `/speckit.implement`
+- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
+- Provide explicit command suggestions: e.g., "Run /speckit.specify with refinement", "Run /speckit.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
+
+### 8. Offer Remediation
+
+Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
+
+## Operating Principles
+
+### Context Efficiency
+
+- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
+- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
+- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
+- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
+
+### Analysis Guidelines
+
+- **NEVER modify files** (this is read-only analysis)
+- **NEVER hallucinate missing sections** (if absent, report them accurately)
+- **Prioritize constitution violations** (these are always CRITICAL)
+- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
+- **Report zero issues gracefully** (emit success report with coverage statistics)
+
+## Context
+
+$ARGUMENTS

.github/agents/speckit.checklist.agent.md

@@ -0,0 +1,295 @@
+---
+description: Generate a custom checklist for the current feature based on user requirements.
+---
+
+## Checklist Purpose: "Unit Tests for English"
+
+**CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain.
+
+**NOT for verification/testing**:
+
+- ❌ NOT "Verify the button clicks correctly"
+- ❌ NOT "Test error handling works"
+- ❌ NOT "Confirm the API returns 200"
+- ❌ NOT checking if code/implementation matches the spec
+
+**FOR requirements quality validation**:
+
+- ✅ "Are visual hierarchy requirements defined for all card types?" (completeness)
+- ✅ "Is 'prominent display' quantified with specific sizing/positioning?" (clarity)
+- ✅ "Are hover state requirements consistent across all interactive elements?" (consistency)
+- ✅ "Are accessibility requirements defined for keyboard navigation?" (coverage)
+- ✅ "Does the spec define what happens when logo image fails to load?" (edge cases)
+
+**Metaphor**: If your spec is code written in English, the checklist is its unit test suite. You're testing whether the requirements are well-written, complete, unambiguous, and ready for implementation - NOT whether the implementation works.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Execution Steps
+
+1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list.
+   - All file paths must be absolute.
+   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST:
+   - Be generated from the user's phrasing + extracted signals from spec/plan/tasks
+   - Only ask about information that materially changes checklist content
+   - Be skipped individually if already unambiguous in `$ARGUMENTS`
+   - Prefer precision over breadth
+
+   Generation algorithm:
+   1. Extract signals: feature domain keywords (e.g., auth, latency, UX, API), risk indicators ("critical", "must", "compliance"), stakeholder hints ("QA", "review", "security team"), and explicit deliverables ("a11y", "rollback", "contracts").
+   2. Cluster signals into candidate focus areas (max 4) ranked by relevance.
+   3. Identify probable audience & timing (author, reviewer, QA, release) if not explicit.
+   4. Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion boundaries, measurable acceptance criteria.
+   5. Formulate questions chosen from these archetypes:
+      - Scope refinement (e.g., "Should this include integration touchpoints with X and Y or stay limited to local module correctness?")
+      - Risk prioritization (e.g., "Which of these potential risk areas should receive mandatory gating checks?")
+      - Depth calibration (e.g., "Is this a lightweight pre-commit sanity list or a formal release gate?")
+      - Audience framing (e.g., "Will this be used by the author only or peers during PR review?")
+      - Boundary exclusion (e.g., "Should we explicitly exclude performance tuning items this round?")
+      - Scenario class gap (e.g., "No recovery flows detected—are rollback / partial failure paths in scope?")
+
+   Question formatting rules:
+   - If presenting options, generate a compact table with columns: Option | Candidate | Why It Matters
+   - Limit to A–E options maximum; omit table if a free-form answer is clearer
+   - Never ask the user to restate what they already said
+   - Avoid speculative categories (no hallucination). If uncertain, ask explicitly: "Confirm whether X belongs in scope."
+
+   Defaults when interaction impossible:
+   - Depth: Standard
+   - Audience: Reviewer (PR) if code-related; Author otherwise
+   - Focus: Top 2 relevance clusters
+
+   Output the questions (label Q1/Q2/Q3). After answers: if ≥2 scenario classes (Alternate / Exception / Recovery / Non-Functional domain) remain unclear, you MAY ask up to TWO more targeted follow‑ups (Q4/Q5) with a one-line justification each (e.g., "Unresolved recovery path risk"). Do not exceed five total questions. Skip escalation if user explicitly declines more.
+
+3. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers:
+   - Derive checklist theme (e.g., security, review, deploy, ux)
+   - Consolidate explicit must-have items mentioned by user
+   - Map focus selections to category scaffolding
+   - Infer any missing context from spec/plan/tasks (do NOT hallucinate)
+
+4. **Load feature context**: Read from FEATURE_DIR:
+   - spec.md: Feature requirements and scope
+   - plan.md (if exists): Technical details, dependencies
+   - tasks.md (if exists): Implementation tasks
+
+   **Context Loading Strategy**:
+   - Load only necessary portions relevant to active focus areas (avoid full-file dumping)
+   - Prefer summarizing long sections into concise scenario/requirement bullets
+   - Use progressive disclosure: add follow-on retrieval only if gaps detected
+   - If source docs are large, generate interim summary items instead of embedding raw text
+
+5. **Generate checklist** - Create "Unit Tests for Requirements":
+   - Create `FEATURE_DIR/checklists/` directory if it doesn't exist
+   - Generate unique checklist filename:
+     - Use short, descriptive name based on domain (e.g., `ux.md`, `api.md`, `security.md`)
+     - Format: `[domain].md`
+   - File handling behavior:
+     - If file does NOT exist: Create new file and number items starting from CHK001
+     - If file exists: Append new items to existing file, continuing from the last CHK ID (e.g., if last item is CHK015, start new items at CHK016)
+   - Never delete or replace existing checklist content - always preserve and append
+
+   **CORE PRINCIPLE - Test the Requirements, Not the Implementation**:
+   Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for:
+   - **Completeness**: Are all necessary requirements present?
+   - **Clarity**: Are requirements unambiguous and specific?
+   - **Consistency**: Do requirements align with each other?
+   - **Measurability**: Can requirements be objectively verified?
+   - **Coverage**: Are all scenarios/edge cases addressed?
+
+   **Category Structure** - Group items by requirement quality dimensions:
+   - **Requirement Completeness** (Are all necessary requirements documented?)
+   - **Requirement Clarity** (Are requirements specific and unambiguous?)
+   - **Requirement Consistency** (Do requirements align without conflicts?)
+   - **Acceptance Criteria Quality** (Are success criteria measurable?)
+   - **Scenario Coverage** (Are all flows/cases addressed?)
+   - **Edge Case Coverage** (Are boundary conditions defined?)
+   - **Non-Functional Requirements** (Performance, Security, Accessibility, etc. - are they specified?)
+   - **Dependencies & Assumptions** (Are they documented and validated?)
+   - **Ambiguities & Conflicts** (What needs clarification?)
+
+   **HOW TO WRITE CHECKLIST ITEMS - "Unit Tests for English"**:
+
+   ❌ **WRONG** (Testing implementation):
+   - "Verify landing page displays 3 episode cards"
+   - "Test hover states work on desktop"
+   - "Confirm logo click navigates home"
+
+   ✅ **CORRECT** (Testing requirements quality):
+   - "Are the exact number and layout of featured episodes specified?" [Completeness]
+   - "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity]
+   - "Are hover state requirements consistent across all interactive elements?" [Consistency]
+   - "Are keyboard navigation requirements defined for all interactive UI?" [Coverage]
+   - "Is the fallback behavior specified when logo image fails to load?" [Edge Cases]
+   - "Are loading states defined for asynchronous episode data?" [Completeness]
+   - "Does the spec define visual hierarchy for competing UI elements?" [Clarity]
+
+   **ITEM STRUCTURE**:
+   Each item should follow this pattern:
+   - Question format asking about requirement quality
+   - Focus on what's WRITTEN (or not written) in the spec/plan
+   - Include quality dimension in brackets [Completeness/Clarity/Consistency/etc.]
+   - Reference spec section `[Spec §X.Y]` when checking existing requirements
+   - Use `[Gap]` marker when checking for missing requirements
+
+   **EXAMPLES BY QUALITY DIMENSION**:
+
+   Completeness:
+   - "Are error handling requirements defined for all API failure modes? [Gap]"
+   - "Are accessibility requirements specified for all interactive elements? [Completeness]"
+   - "Are mobile breakpoint requirements defined for responsive layouts? [Gap]"
+
+   Clarity:
+   - "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]"
+   - "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]"
+   - "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]"
+
+   Consistency:
+   - "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]"
+   - "Are card component requirements consistent between landing and detail pages? [Consistency]"
+
+   Coverage:
+   - "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]"
+   - "Are concurrent user interaction scenarios addressed? [Coverage, Gap]"
+   - "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]"
+
+   Measurability:
+   - "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]"
+   - "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]"
+
+   **Scenario Classification & Coverage** (Requirements Quality Focus):
+   - Check if requirements exist for: Primary, Alternate, Exception/Error, Recovery, Non-Functional scenarios
+   - For each scenario class, ask: "Are [scenario type] requirements complete, clear, and consistent?"
+   - If scenario class missing: "Are [scenario type] requirements intentionally excluded or missing? [Gap]"
+   - Include resilience/rollback when state mutation occurs: "Are rollback requirements defined for migration failures? [Gap]"
+
+   **Traceability Requirements**:
+   - MINIMUM: ≥80% of items MUST include at least one traceability reference
+   - Each item should reference: spec section `[Spec §X.Y]`, or use markers: `[Gap]`, `[Ambiguity]`, `[Conflict]`, `[Assumption]`
+   - If no ID system exists: "Is a requirement & acceptance criteria ID scheme established? [Traceability]"
+
+   **Surface & Resolve Issues** (Requirements Quality Problems):
+   Ask questions about the requirements themselves:
+   - Ambiguities: "Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec §NFR-1]"
+   - Conflicts: "Do navigation requirements conflict between §FR-10 and §FR-10a? [Conflict]"
+   - Assumptions: "Is the assumption of 'always available podcast API' validated? [Assumption]"
+   - Dependencies: "Are external podcast API requirements documented? [Dependency, Gap]"
+   - Missing definitions: "Is 'visual hierarchy' defined with measurable criteria? [Gap]"
+
+   **Content Consolidation**:
+   - Soft cap: If raw candidate items > 40, prioritize by risk/impact
+   - Merge near-duplicates checking the same requirement aspect
+   - If >5 low-impact edge cases, create one item: "Are edge cases X, Y, Z addressed in requirements? [Coverage]"
+
+   **🚫 ABSOLUTELY PROHIBITED** - These make it an implementation test, not a requirements test:
+   - ❌ Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior
+   - ❌ References to code execution, user actions, system behavior
+   - ❌ "Displays correctly", "works properly", "functions as expected"
+   - ❌ "Click", "navigate", "render", "load", "execute"
+   - ❌ Test cases, test plans, QA procedures
+   - ❌ Implementation details (frameworks, APIs, algorithms)
+
+   **✅ REQUIRED PATTERNS** - These test requirements quality:
+   - ✅ "Are [requirement type] defined/specified/documented for [scenario]?"
+   - ✅ "Is [vague term] quantified/clarified with specific criteria?"
+   - ✅ "Are requirements consistent between [section A] and [section B]?"
+   - ✅ "Can [requirement] be objectively measured/verified?"
+   - ✅ "Are [edge cases/scenarios] addressed in requirements?"
+   - ✅ "Does the spec define [missing aspect]?"
+
+6. **Structure Reference**: Generate the checklist following the canonical template in `.specify/templates/checklist-template.md` for title, meta section, category headings, and ID formatting. If template is unavailable, use: H1 title, purpose/created meta lines, `##` category sections containing `- [ ] CHK### <requirement item>` lines with globally incrementing IDs starting at CHK001.
+
+7. **Report**: Output full path to checklist file, item count, and summarize whether the run created a new file or appended to an existing one. Summarize:
+   - Focus areas selected
+   - Depth level
+   - Actor/timing
+   - Any explicit user-specified must-have items incorporated
+
+**Important**: Each `/speckit.checklist` command invocation uses a short, descriptive checklist filename and either creates a new file or appends to an existing one. This allows:
+
+- Multiple checklists of different types (e.g., `ux.md`, `test.md`, `security.md`)
+- Simple, memorable filenames that indicate checklist purpose
+- Easy identification and navigation in the `checklists/` folder
+
+To avoid clutter, use descriptive types and clean up obsolete checklists when done.
+
+## Example Checklist Types & Sample Items
+
+**UX Requirements Quality:** `ux.md`
+
+Sample items (testing the requirements, NOT the implementation):
+
+- "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]"
+- "Is the number and positioning of UI elements explicitly specified? [Completeness, Spec §FR-1]"
+- "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]"
+- "Are accessibility requirements specified for all interactive elements? [Coverage, Gap]"
+- "Is fallback behavior defined when images fail to load? [Edge Case, Gap]"
+- "Can 'prominent display' be objectively measured? [Measurability, Spec §FR-4]"
+
+**API Requirements Quality:** `api.md`
+
+Sample items:
+
+- "Are error response formats specified for all failure scenarios? [Completeness]"
+- "Are rate limiting requirements quantified with specific thresholds? [Clarity]"
+- "Are authentication requirements consistent across all endpoints? [Consistency]"
+- "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]"
+- "Is versioning strategy documented in requirements? [Gap]"
+
+**Performance Requirements Quality:** `performance.md`
+
+Sample items:
+
+- "Are performance requirements quantified with specific metrics? [Clarity]"
+- "Are performance targets defined for all critical user journeys? [Coverage]"
+- "Are performance requirements under different load conditions specified? [Completeness]"
+- "Can performance requirements be objectively measured? [Measurability]"
+- "Are degradation requirements defined for high-load scenarios? [Edge Case, Gap]"
+
+**Security Requirements Quality:** `security.md`
+
+Sample items:
+
+- "Are authentication requirements specified for all protected resources? [Coverage]"
+- "Are data protection requirements defined for sensitive information? [Completeness]"
+- "Is the threat model documented and requirements aligned to it? [Traceability]"
+- "Are security requirements consistent with compliance obligations? [Consistency]"
+- "Are security failure/breach response requirements defined? [Gap, Exception Flow]"
+
+## Anti-Examples: What NOT To Do
+
+**❌ WRONG - These test implementation, not requirements:**
+
+```markdown
+- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001]
+- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003]
+- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010]
+- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005]
+```
+
+**✅ CORRECT - These test requirements quality:**
+
+```markdown
+- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001]
+- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003]
+- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010]
+- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005]
+- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap]
+- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001]
+```
+
+**Key Differences:**
+
+- Wrong: Tests if the system works correctly
+- Correct: Tests if the requirements are written correctly
+- Wrong: Verification of behavior
+- Correct: Validation of requirement quality
+- Wrong: "Does it do X?"
+- Correct: "Is X clearly specified?"

.github/agents/speckit.clarify.agent.md

@@ -0,0 +1,181 @@
+---
+description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
+handoffs: 
+  - label: Build Technical Plan
+    agent: speckit.plan
+    prompt: Create a plan for the spec. I am building with...
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.
+
+Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/speckit.plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.
+
+Execution steps:
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields:
+   - `FEATURE_DIR`
+   - `FEATURE_SPEC`
+   - (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.)
+   - If JSON parsing fails, abort and instruct user to re-run `/speckit.specify` or verify feature branch environment.
+   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).
+
+   Functional Scope & Behavior:
+   - Core user goals & success criteria
+   - Explicit out-of-scope declarations
+   - User roles / personas differentiation
+
+   Domain & Data Model:
+   - Entities, attributes, relationships
+   - Identity & uniqueness rules
+   - Lifecycle/state transitions
+   - Data volume / scale assumptions
+
+   Interaction & UX Flow:
+   - Critical user journeys / sequences
+   - Error/empty/loading states
+   - Accessibility or localization notes
+
+   Non-Functional Quality Attributes:
+   - Performance (latency, throughput targets)
+   - Scalability (horizontal/vertical, limits)
+   - Reliability & availability (uptime, recovery expectations)
+   - Observability (logging, metrics, tracing signals)
+   - Security & privacy (authN/Z, data protection, threat assumptions)
+   - Compliance / regulatory constraints (if any)
+
+   Integration & External Dependencies:
+   - External services/APIs and failure modes
+   - Data import/export formats
+   - Protocol/versioning assumptions
+
+   Edge Cases & Failure Handling:
+   - Negative scenarios
+   - Rate limiting / throttling
+   - Conflict resolution (e.g., concurrent edits)
+
+   Constraints & Tradeoffs:
+   - Technical constraints (language, storage, hosting)
+   - Explicit tradeoffs or rejected alternatives
+
+   Terminology & Consistency:
+   - Canonical glossary terms
+   - Avoided synonyms / deprecated terms
+
+   Completion Signals:
+   - Acceptance criteria testability
+   - Measurable Definition of Done style indicators
+
+   Misc / Placeholders:
+   - TODO markers / unresolved decisions
+   - Ambiguous adjectives ("robust", "intuitive") lacking quantification
+
+   For each category with Partial or Missing status, add a candidate question opportunity unless:
+   - Clarification would not materially change implementation or validation strategy
+   - Information is better deferred to planning phase (note internally)
+
+3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:
+    - Maximum of 5 total questions across the whole session.
+    - Each question must be answerable with EITHER:
+       - A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
+       - A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").
+    - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
+    - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
+    - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
+    - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
+    - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.
+
+4. Sequential questioning loop (interactive):
+    - Present EXACTLY ONE question at a time.
+    - For multiple‑choice questions:
+       - **Analyze all options** and determine the **most suitable option** based on:
+          - Best practices for the project type
+          - Common patterns in similar implementations
+          - Risk reduction (security, performance, maintainability)
+          - Alignment with any explicit project goals or constraints visible in the spec
+       - Present your **recommended option prominently** at the top with clear reasoning (1-2 sentences explaining why this is the best choice).
+       - Format as: `**Recommended:** Option [X] - <reasoning>`
+       - Then render all options as a Markdown table:
+
+       | Option | Description |
+       |--------|-------------|
+       | A | <Option A description> |
+       | B | <Option B description> |
+       | C | <Option C description> (add D/E as needed up to 5) |
+       | Short | Provide a different short answer (<=5 words) (Include only if free-form alternative is appropriate) |
+
+       - After the table, add: `You can reply with the option letter (e.g., "A"), accept the recommendation by saying "yes" or "recommended", or provide your own short answer.`
+    - For short‑answer style (no meaningful discrete options):
+       - Provide your **suggested answer** based on best practices and context.
+       - Format as: `**Suggested:** <your proposed answer> - <brief reasoning>`
+       - Then output: `Format: Short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.`
+    - After the user answers:
+       - If the user replies with "yes", "recommended", or "suggested", use your previously stated recommendation/suggestion as the answer.
+       - Otherwise, validate the answer maps to one option or fits the <=5 word constraint.
+       - If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance).
+       - Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question.
+    - Stop asking further questions when:
+       - All critical ambiguities resolved early (remaining queued items become unnecessary), OR
+       - User signals completion ("done", "good", "no more"), OR
+       - You reach 5 asked questions.
+    - Never reveal future queued questions in advance.
+    - If no valid questions exist at start, immediately report no critical ambiguities.
+
+5. Integration after EACH accepted answer (incremental update approach):
+    - Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.
+    - For the first integrated answer in this session:
+       - Ensure a `## Clarifications` section exists (create it just after the highest-level contextual/overview section per the spec template if missing).
+       - Under it, create (if not present) a `### Session YYYY-MM-DD` subheading for today.
+    - Append a bullet line immediately after acceptance: `- Q: <question> → A: <final answer>`.
+    - Then immediately apply the clarification to the most appropriate section(s):
+       - Functional ambiguity → Update or add a bullet in Functional Requirements.
+       - User interaction / actor distinction → Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.
+       - Data shape / entities → Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.
+       - Non-functional constraint → Add/modify measurable criteria in Non-Functional / Quality Attributes section (convert vague adjective to metric or explicit target).
+       - Edge case / negative flow → Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).
+       - Terminology conflict → Normalize term across spec; retain original only if necessary by adding `(formerly referred to as "X")` once.
+    - If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.
+    - Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).
+    - Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
+    - Keep each inserted clarification minimal and testable (avoid narrative drift).
+
+6. Validation (performed after EACH write plus final pass):
+   - Clarifications session contains exactly one bullet per accepted answer (no duplicates).
+   - Total asked (accepted) questions ≤ 5.
+   - Updated sections contain no lingering vague placeholders the new answer was meant to resolve.
+   - No contradictory earlier statement remains (scan for now-invalid alternative choices removed).
+   - Markdown structure valid; only allowed new headings: `## Clarifications`, `### Session YYYY-MM-DD`.
+   - Terminology consistency: same canonical term used across all updated sections.
+
+7. Write the updated spec back to `FEATURE_SPEC`.
+
+8. Report completion (after questioning loop ends or early termination):
+   - Number of questions asked & answered.
+   - Path to updated spec.
+   - Sections touched (list names).
+   - Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
+   - If any Outstanding or Deferred remain, recommend whether to proceed to `/speckit.plan` or run `/speckit.clarify` again later post-plan.
+   - Suggested next command.
+
+Behavior rules:
+
+- If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
+- If spec file missing, instruct user to run `/speckit.specify` first (do not create a new spec here).
+- Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions).
+- Avoid speculative tech stack questions unless the absence blocks functional clarity.
+- Respect user early termination signals ("stop", "done", "proceed").
+- If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.
+- If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.
+
+Context for prioritization: $ARGUMENTS

.github/agents/speckit.constitution.agent.md

@@ -0,0 +1,84 @@
+---
+description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.
+handoffs: 
+  - label: Build Specification
+    agent: speckit.specify
+    prompt: Implement the feature specification based on the updated constitution. I want to build...
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+You are updating the project constitution at `.specify/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.
+
+**Note**: If `.specify/memory/constitution.md` does not exist yet, it should have been initialized from `.specify/templates/constitution-template.md` during project setup. If it's missing, copy the template first.
+
+Follow this execution flow:
+
+1. Load the existing constitution at `.specify/memory/constitution.md`.
+   - Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`.
+   **IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly.
+
+2. Collect/derive values for placeholders:
+   - If user input (conversation) supplies a value, use it.
+   - Otherwise infer from existing repo context (README, docs, prior constitution versions if embedded).
+   - For governance dates: `RATIFICATION_DATE` is the original adoption date (if unknown ask or mark TODO), `LAST_AMENDED_DATE` is today if changes are made, otherwise keep previous.
+   - `CONSTITUTION_VERSION` must increment according to semantic versioning rules:
+     - MAJOR: Backward incompatible governance/principle removals or redefinitions.
+     - MINOR: New principle/section added or materially expanded guidance.
+     - PATCH: Clarifications, wording, typo fixes, non-semantic refinements.
+   - If version bump type ambiguous, propose reasoning before finalizing.
+
+3. Draft the updated constitution content:
+   - Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left).
+   - Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance.
+   - Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious.
+   - Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations.
+
+4. Consistency propagation checklist (convert prior checklist into active validations):
+   - Read `.specify/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles.
+   - Read `.specify/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints.
+   - Read `.specify/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline).
+   - Read each command file in `.specify/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required.
+   - Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed.
+
+5. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update):
+   - Version change: old → new
+   - List of modified principles (old title → new title if renamed)
+   - Added sections
+   - Removed sections
+   - Templates requiring updates (✅ updated / ⚠ pending) with file paths
+   - Follow-up TODOs if any placeholders intentionally deferred.
+
+6. Validation before final output:
+   - No remaining unexplained bracket tokens.
+   - Version line matches report.
+   - Dates ISO format YYYY-MM-DD.
+   - Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate).
+
+7. Write the completed constitution back to `.specify/memory/constitution.md` (overwrite).
+
+8. Output a final summary to the user with:
+   - New version and bump rationale.
+   - Any files flagged for manual follow-up.
+   - Suggested commit message (e.g., `docs: amend constitution to vX.Y.Z (principle additions + governance update)`).
+
+Formatting & Style Requirements:
+
+- Use Markdown headings exactly as in the template (do not demote/promote levels).
+- Wrap long rationale lines to keep readability (<100 chars ideally) but do not hard enforce with awkward breaks.
+- Keep a single blank line between sections.
+- Avoid trailing whitespace.
+
+If the user supplies partial updates (e.g., only one principle revision), still perform validation and version decision steps.
+
+If critical info missing (e.g., ratification date truly unknown), insert `TODO(<FIELD_NAME>): explanation` and include in the Sync Impact Report under deferred items.
+
+Do not create a new template; always operate on the existing `.specify/memory/constitution.md` file.

.github/agents/speckit.implement.agent.md

@@ -0,0 +1,135 @@
+---
+description: Execute the implementation plan by processing and executing all tasks defined in tasks.md
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Check checklists status** (if FEATURE_DIR/checklists/ exists):
+   - Scan all checklist files in the checklists/ directory
+   - For each checklist, count:
+     - Total items: All lines matching `- [ ]` or `- [X]` or `- [x]`
+     - Completed items: Lines matching `- [X]` or `- [x]`
+     - Incomplete items: Lines matching `- [ ]`
+   - Create a status table:
+
+     ```text
+     | Checklist | Total | Completed | Incomplete | Status |
+     |-----------|-------|-----------|------------|--------|
+     | ux.md     | 12    | 12        | 0          | ✓ PASS |
+     | test.md   | 8     | 5         | 3          | ✗ FAIL |
+     | security.md | 6   | 6         | 0          | ✓ PASS |
+     ```
+
+   - Calculate overall status:
+     - **PASS**: All checklists have 0 incomplete items
+     - **FAIL**: One or more checklists have incomplete items
+
+   - **If any checklist is incomplete**:
+     - Display the table with incomplete item counts
+     - **STOP** and ask: "Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)"
+     - Wait for user response before continuing
+     - If user says "no" or "wait" or "stop", halt execution
+     - If user says "yes" or "proceed" or "continue", proceed to step 3
+
+   - **If all checklists are complete**:
+     - Display the table showing all checklists passed
+     - Automatically proceed to step 3
+
+3. Load and analyze the implementation context:
+   - **REQUIRED**: Read tasks.md for the complete task list and execution plan
+   - **REQUIRED**: Read plan.md for tech stack, architecture, and file structure
+   - **IF EXISTS**: Read data-model.md for entities and relationships
+   - **IF EXISTS**: Read contracts/ for API specifications and test requirements
+   - **IF EXISTS**: Read research.md for technical decisions and constraints
+   - **IF EXISTS**: Read quickstart.md for integration scenarios
+
+4. **Project Setup Verification**:
+   - **REQUIRED**: Create/verify ignore files based on actual project setup:
+
+   **Detection & Creation Logic**:
+   - Check if the following command succeeds to determine if the repository is a git repo (create/verify .gitignore if so):
+
+     ```sh
+     git rev-parse --git-dir 2>/dev/null
+     ```
+
+   - Check if Dockerfile* exists or Docker in plan.md → create/verify .dockerignore
+   - Check if .eslintrc* exists → create/verify .eslintignore
+   - Check if eslint.config.* exists → ensure the config's `ignores` entries cover required patterns
+   - Check if .prettierrc* exists → create/verify .prettierignore
+   - Check if .npmrc or package.json exists → create/verify .npmignore (if publishing)
+   - Check if terraform files (*.tf) exist → create/verify .terraformignore
+   - Check if .helmignore needed (helm charts present) → create/verify .helmignore
+
+   **If ignore file already exists**: Verify it contains essential patterns, append missing critical patterns only
+   **If ignore file missing**: Create with full pattern set for detected technology
+
+   **Common Patterns by Technology** (from plan.md tech stack):
+   - **Node.js/JavaScript/TypeScript**: `node_modules/`, `dist/`, `build/`, `*.log`, `.env*`
+   - **Python**: `__pycache__/`, `*.pyc`, `.venv/`, `venv/`, `dist/`, `*.egg-info/`
+   - **Java**: `target/`, `*.class`, `*.jar`, `.gradle/`, `build/`
+   - **C#/.NET**: `bin/`, `obj/`, `*.user`, `*.suo`, `packages/`
+   - **Go**: `*.exe`, `*.test`, `vendor/`, `*.out`
+   - **Ruby**: `.bundle/`, `log/`, `tmp/`, `*.gem`, `vendor/bundle/`
+   - **PHP**: `vendor/`, `*.log`, `*.cache`, `*.env`
+   - **Rust**: `target/`, `debug/`, `release/`, `*.rs.bk`, `*.rlib`, `*.prof*`, `.idea/`, `*.log`, `.env*`
+   - **Kotlin**: `build/`, `out/`, `.gradle/`, `.idea/`, `*.class`, `*.jar`, `*.iml`, `*.log`, `.env*`
+   - **C++**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.so`, `*.a`, `*.exe`, `*.dll`, `.idea/`, `*.log`, `.env*`
+   - **C**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.a`, `*.so`, `*.exe`, `autom4te.cache/`, `config.status`, `config.log`, `.idea/`, `*.log`, `.env*`
+   - **Swift**: `.build/`, `DerivedData/`, `*.swiftpm/`, `Packages/`
+   - **R**: `.Rproj.user/`, `.Rhistory`, `.RData`, `.Ruserdata`, `*.Rproj`, `packrat/`, `renv/`
+   - **Universal**: `.DS_Store`, `Thumbs.db`, `*.tmp`, `*.swp`, `.vscode/`, `.idea/`
+
+   **Tool-Specific Patterns**:
+   - **Docker**: `node_modules/`, `.git/`, `Dockerfile*`, `.dockerignore`, `*.log*`, `.env*`, `coverage/`
+   - **ESLint**: `node_modules/`, `dist/`, `build/`, `coverage/`, `*.min.js`
+   - **Prettier**: `node_modules/`, `dist/`, `build/`, `coverage/`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
+   - **Terraform**: `.terraform/`, `*.tfstate*`, `*.tfvars`, `.terraform.lock.hcl`
+   - **Kubernetes/k8s**: `*.secret.yaml`, `secrets/`, `.kube/`, `kubeconfig*`, `*.key`, `*.crt`
+
+5. Parse tasks.md structure and extract:
+   - **Task phases**: Setup, Tests, Core, Integration, Polish
+   - **Task dependencies**: Sequential vs parallel execution rules
+   - **Task details**: ID, description, file paths, parallel markers [P]
+   - **Execution flow**: Order and dependency requirements
+
+6. Execute implementation following the task plan:
+   - **Phase-by-phase execution**: Complete each phase before moving to the next
+   - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together  
+   - **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks
+   - **File-based coordination**: Tasks affecting the same files must run sequentially
+   - **Validation checkpoints**: Verify each phase completion before proceeding
+
+7. Implementation execution rules:
+   - **Setup first**: Initialize project structure, dependencies, configuration
+   - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios
+   - **Core development**: Implement models, services, CLI commands, endpoints
+   - **Integration work**: Database connections, middleware, logging, external services
+   - **Polish and validation**: Unit tests, performance optimization, documentation
+
+8. Progress tracking and error handling:
+   - Report progress after each completed task
+   - Halt execution if any non-parallel task fails
+   - For parallel tasks [P], continue with successful tasks, report failed ones
+   - Provide clear error messages with context for debugging
+   - Suggest next steps if implementation cannot proceed
+   - **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file.
+
+9. Completion validation:
+   - Verify all required tasks are completed
+   - Check that implemented features match the original specification
+   - Validate that tests pass and coverage meets requirements
+   - Confirm the implementation follows the technical plan
+   - Report final status with summary of completed work
+
+Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/speckit.tasks` first to regenerate the task list.

.github/agents/speckit.plan.agent.md

@@ -0,0 +1,90 @@
+---
+description: Execute the implementation planning workflow using the plan template to generate design artifacts.
+handoffs: 
+  - label: Create Tasks
+    agent: speckit.tasks
+    prompt: Break the plan into tasks
+    send: true
+  - label: Create Checklist
+    agent: speckit.checklist
+    prompt: Create a checklist for the following domain...
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. **Setup**: Run `.specify/scripts/bash/setup-plan.sh --json` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Load context**: Read FEATURE_SPEC and `.specify/memory/constitution.md`. Load IMPL_PLAN template (already copied).
+
+3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to:
+   - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
+   - Fill Constitution Check section from constitution
+   - Evaluate gates (ERROR if violations unjustified)
+   - Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
+   - Phase 1: Generate data-model.md, contracts/, quickstart.md
+   - Phase 1: Update agent context by running the agent script
+   - Re-evaluate Constitution Check post-design
+
+4. **Stop and report**: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.
+
+## Phases
+
+### Phase 0: Outline & Research
+
+1. **Extract unknowns from Technical Context** above:
+   - For each NEEDS CLARIFICATION → research task
+   - For each dependency → best practices task
+   - For each integration → patterns task
+
+2. **Generate and dispatch research agents**:
+
+   ```text
+   For each unknown in Technical Context:
+     Task: "Research {unknown} for {feature context}"
+   For each technology choice:
+     Task: "Find best practices for {tech} in {domain}"
+   ```
+
+3. **Consolidate findings** in `research.md` using format:
+   - Decision: [what was chosen]
+   - Rationale: [why chosen]
+   - Alternatives considered: [what else evaluated]
+
+**Output**: research.md with all NEEDS CLARIFICATION resolved
+
+### Phase 1: Design & Contracts
+
+**Prerequisites:** `research.md` complete
+
+1. **Extract entities from feature spec** → `data-model.md`:
+   - Entity name, fields, relationships
+   - Validation rules from requirements
+   - State transitions if applicable
+
+2. **Define interface contracts** (if project has external interfaces) → `/contracts/`:
+   - Identify what interfaces the project exposes to users or other systems
+   - Document the contract format appropriate for the project type
+   - Examples: public APIs for libraries, command schemas for CLI tools, endpoints for web services, grammars for parsers, UI contracts for applications
+   - Skip if project is purely internal (build scripts, one-off tools, etc.)
+
+3. **Agent context update**:
+   - Run `.specify/scripts/bash/update-agent-context.sh copilot`
+   - These scripts detect which AI agent is in use
+   - Update the appropriate agent-specific context file
+   - Add only new technology from current plan
+   - Preserve manual additions between markers
+
+**Output**: data-model.md, /contracts/*, quickstart.md, agent-specific file
+
+## Key rules
+
+- Use absolute paths
+- ERROR on gate failures or unresolved clarifications

.github/agents/speckit.specify.agent.md

@@ -0,0 +1,258 @@
+---
+description: Create or update the feature specification from a natural language feature description.
+handoffs: 
+  - label: Build Technical Plan
+    agent: speckit.plan
+    prompt: Create a plan for the spec. I am building with...
+  - label: Clarify Spec Requirements
+    agent: speckit.clarify
+    prompt: Clarify specification requirements
+    send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+The text the user typed after `/speckit.specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `$ARGUMENTS` appears literally below. Do not ask the user to repeat it unless they provided an empty command.
+
+Given that feature description, do this:
+
+1. **Generate a concise short name** (2-4 words) for the branch:
+   - Analyze the feature description and extract the most meaningful keywords
+   - Create a 2-4 word short name that captures the essence of the feature
+   - Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
+   - Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)
+   - Keep it concise but descriptive enough to understand the feature at a glance
+   - Examples:
+     - "I want to add user authentication" → "user-auth"
+     - "Implement OAuth2 integration for the API" → "oauth2-api-integration"
+     - "Create a dashboard for analytics" → "analytics-dashboard"
+     - "Fix payment processing timeout bug" → "fix-payment-timeout"
+
+2. **Check for existing branches before creating new one**:
+
+   a. First, fetch all remote branches to ensure we have the latest information:
+
+      ```bash
+      git fetch --all --prune
+      ```
+
+   b. Find the highest feature number across all sources for the short-name:
+      - Remote branches: `git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'`
+      - Local branches: `git branch | grep -E '^[* ]*[0-9]+-<short-name>$'`
+      - Specs directories: Check for directories matching `specs/[0-9]+-<short-name>`
+
+   c. Determine the next available number:
+      - Extract all numbers from all three sources
+      - Find the highest number N
+      - Use N+1 for the new branch number
+
+   d. Run the script `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS"` with the calculated number and short-name:
+      - Pass `--number N+1` and `--short-name "your-short-name"` along with the feature description
+      - Bash example: `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" --json --number 5 --short-name "user-auth" "Add user authentication"`
+      - PowerShell example: `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" -Json -Number 5 -ShortName "user-auth" "Add user authentication"`
+
+   **IMPORTANT**:
+   - Check all three sources (remote branches, local branches, specs directories) to find the highest number
+   - Only match branches/directories with the exact short-name pattern
+   - If no existing branches/directories found with this short-name, start with number 1
+   - You must only ever run this script once per feature
+   - The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for
+   - The JSON output will contain BRANCH_NAME and SPEC_FILE paths
+   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot")
+
+3. Load `.specify/templates/spec-template.md` to understand required sections.
+
+4. Follow this execution flow:
+
+    1. Parse user description from Input
+       If empty: ERROR "No feature description provided"
+    2. Extract key concepts from description
+       Identify: actors, actions, data, constraints
+    3. For unclear aspects:
+       - Make informed guesses based on context and industry standards
+       - Only mark with [NEEDS CLARIFICATION: specific question] if:
+         - The choice significantly impacts feature scope or user experience
+         - Multiple reasonable interpretations exist with different implications
+         - No reasonable default exists
+       - **LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total**
+       - Prioritize clarifications by impact: scope > security/privacy > user experience > technical details
+    4. Fill User Scenarios & Testing section
+       If no clear user flow: ERROR "Cannot determine user scenarios"
+    5. Generate Functional Requirements
+       Each requirement must be testable
+       Use reasonable defaults for unspecified details (document assumptions in Assumptions section)
+    6. Define Success Criteria
+       Create measurable, technology-agnostic outcomes
+       Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion)
+       Each criterion must be verifiable without implementation details
+    7. Identify Key Entities (if data involved)
+    8. Return: SUCCESS (spec ready for planning)
+
+5. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
+
+6. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria:
+
+   a. **Create Spec Quality Checklist**: Generate a checklist file at `FEATURE_DIR/checklists/requirements.md` using the checklist template structure with these validation items:
+
+      ```markdown
+      # Specification Quality Checklist: [FEATURE NAME]
+      
+      **Purpose**: Validate specification completeness and quality before proceeding to planning
+      **Created**: [DATE]
+      **Feature**: [Link to spec.md]
+      
+      ## Content Quality
+      
+      - [ ] No implementation details (languages, frameworks, APIs)
+      - [ ] Focused on user value and business needs
+      - [ ] Written for non-technical stakeholders
+      - [ ] All mandatory sections completed
+      
+      ## Requirement Completeness
+      
+      - [ ] No [NEEDS CLARIFICATION] markers remain
+      - [ ] Requirements are testable and unambiguous
+      - [ ] Success criteria are measurable
+      - [ ] Success criteria are technology-agnostic (no implementation details)
+      - [ ] All acceptance scenarios are defined
+      - [ ] Edge cases are identified
+      - [ ] Scope is clearly bounded
+      - [ ] Dependencies and assumptions identified
+      
+      ## Feature Readiness
+      
+      - [ ] All functional requirements have clear acceptance criteria
+      - [ ] User scenarios cover primary flows
+      - [ ] Feature meets measurable outcomes defined in Success Criteria
+      - [ ] No implementation details leak into specification
+      
+      ## Notes
+      
+      - Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`
+      ```
+
+   b. **Run Validation Check**: Review the spec against each checklist item:
+      - For each item, determine if it passes or fails
+      - Document specific issues found (quote relevant spec sections)
+
+   c. **Handle Validation Results**:
+
+      - **If all items pass**: Mark checklist complete and proceed to step 6
+
+      - **If items fail (excluding [NEEDS CLARIFICATION])**:
+        1. List the failing items and specific issues
+        2. Update the spec to address each issue
+        3. Re-run validation until all items pass (max 3 iterations)
+        4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user
+
+      - **If [NEEDS CLARIFICATION] markers remain**:
+        1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec
+        2. **LIMIT CHECK**: If more than 3 markers exist, keep only the 3 most critical (by scope/security/UX impact) and make informed guesses for the rest
+        3. For each clarification needed (max 3), present options to user in this format:
+
+           ```markdown
+           ## Question [N]: [Topic]
+           
+           **Context**: [Quote relevant spec section]
+           
+           **What we need to know**: [Specific question from NEEDS CLARIFICATION marker]
+           
+           **Suggested Answers**:
+           
+           | Option | Answer | Implications |
+           |--------|--------|--------------|
+           | A      | [First suggested answer] | [What this means for the feature] |
+           | B      | [Second suggested answer] | [What this means for the feature] |
+           | C      | [Third suggested answer] | [What this means for the feature] |
+           | Custom | Provide your own answer | [Explain how to provide custom input] |
+           
+           **Your choice**: _[Wait for user response]_
+           ```
+
+        4. **CRITICAL - Table Formatting**: Ensure markdown tables are properly formatted:
+           - Use consistent spacing with pipes aligned
+           - Each cell should have spaces around content: `| Content |` not `|Content|`
+           - Header separator must have at least 3 dashes: `|--------|`
+           - Test that the table renders correctly in markdown preview
+        5. Number questions sequentially (Q1, Q2, Q3 - max 3 total)
+        6. Present all questions together before waiting for responses
+        7. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")
+        8. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer
+        9. Re-run validation after all clarifications are resolved
+
+   d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status
+
+7. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`).
+
+**NOTE:** The script creates and checks out the new branch and initializes the spec file before writing.
+
+## General Guidelines
+
+## Quick Guidelines
+
+- Focus on **WHAT** users need and **WHY**.
+- Avoid HOW to implement (no tech stack, APIs, code structure).
+- Written for business stakeholders, not developers.
+- DO NOT create any checklists that are embedded in the spec. That will be a separate command.
+
+### Section Requirements
+
+- **Mandatory sections**: Must be completed for every feature
+- **Optional sections**: Include only when relevant to the feature
+- When a section doesn't apply, remove it entirely (don't leave as "N/A")
+
+### For AI Generation
+
+When creating this spec from a user prompt:
+
+1. **Make informed guesses**: Use context, industry standards, and common patterns to fill gaps
+2. **Document assumptions**: Record reasonable defaults in the Assumptions section
+3. **Limit clarifications**: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that:
+   - Significantly impact feature scope or user experience
+   - Have multiple reasonable interpretations with different implications
+   - Lack any reasonable default
+4. **Prioritize clarifications**: scope > security/privacy > user experience > technical details
+5. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
+6. **Common areas needing clarification** (only if no reasonable default exists):
+   - Feature scope and boundaries (include/exclude specific use cases)
+   - User types and permissions (if multiple conflicting interpretations possible)
+   - Security/compliance requirements (when legally/financially significant)
+
+**Examples of reasonable defaults** (don't ask about these):
+
+- Data retention: Industry-standard practices for the domain
+- Performance targets: Standard web/mobile app expectations unless specified
+- Error handling: User-friendly messages with appropriate fallbacks
+- Authentication method: Standard session-based or OAuth2 for web apps
+- Integration patterns: Use project-appropriate patterns (REST/GraphQL for web services, function calls for libraries, CLI args for tools, etc.)
+
+### Success Criteria Guidelines
+
+Success criteria must be:
+
+1. **Measurable**: Include specific metrics (time, percentage, count, rate)
+2. **Technology-agnostic**: No mention of frameworks, languages, databases, or tools
+3. **User-focused**: Describe outcomes from user/business perspective, not system internals
+4. **Verifiable**: Can be tested/validated without knowing implementation details
+
+**Good examples**:
+
+- "Users can complete checkout in under 3 minutes"
+- "System supports 10,000 concurrent users"
+- "95% of searches return results in under 1 second"
+- "Task completion rate improves by 40%"
+
+**Bad examples** (implementation-focused):
+
+- "API response time is under 200ms" (too technical, use "Users see results instantly")
+- "Database can handle 1000 TPS" (implementation detail, use user-facing metric)
+- "React components render efficiently" (framework-specific)
+- "Redis cache hit rate above 80%" (technology-specific)

.github/agents/speckit.tasks.agent.md

@@ -0,0 +1,137 @@
+---
+description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
+handoffs: 
+  - label: Analyze For Consistency
+    agent: speckit.analyze
+    prompt: Run a project analysis for consistency
+    send: true
+  - label: Implement Project
+    agent: speckit.implement
+    prompt: Start the implementation in phases
+    send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Load design documents**: Read from FEATURE_DIR:
+   - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
+   - **Optional**: data-model.md (entities), contracts/ (interface contracts), research.md (decisions), quickstart.md (test scenarios)
+   - Note: Not all projects have all documents. Generate tasks based on what's available.
+
+3. **Execute task generation workflow**:
+   - Load plan.md and extract tech stack, libraries, project structure
+   - Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)
+   - If data-model.md exists: Extract entities and map to user stories
+   - If contracts/ exists: Map interface contracts to user stories
+   - If research.md exists: Extract decisions for setup tasks
+   - Generate tasks organized by user story (see Task Generation Rules below)
+   - Generate dependency graph showing user story completion order
+   - Create parallel execution examples per user story
+   - Validate task completeness (each user story has all needed tasks, independently testable)
+
+4. **Generate tasks.md**: Use `.specify/templates/tasks-template.md` as structure, fill with:
+   - Correct feature name from plan.md
+   - Phase 1: Setup tasks (project initialization)
+   - Phase 2: Foundational tasks (blocking prerequisites for all user stories)
+   - Phase 3+: One phase per user story (in priority order from spec.md)
+   - Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks
+   - Final Phase: Polish & cross-cutting concerns
+   - All tasks must follow the strict checklist format (see Task Generation Rules below)
+   - Clear file paths for each task
+   - Dependencies section showing story completion order
+   - Parallel execution examples per story
+   - Implementation strategy section (MVP first, incremental delivery)
+
+5. **Report**: Output path to generated tasks.md and summary:
+   - Total task count
+   - Task count per user story
+   - Parallel opportunities identified
+   - Independent test criteria for each story
+   - Suggested MVP scope (typically just User Story 1)
+   - Format validation: Confirm ALL tasks follow the checklist format (checkbox, ID, labels, file paths)
+
+Context for task generation: $ARGUMENTS
+
+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.
+
+## Task Generation Rules
+
+**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.
+
+**Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach.
+
+### Checklist Format (REQUIRED)
+
+Every task MUST strictly follow this format:
+
+```text
+- [ ] [TaskID] [P?] [Story?] Description with file path
+```
+
+**Format Components**:
+
+1. **Checkbox**: ALWAYS start with `- [ ]` (markdown checkbox)
+2. **Task ID**: Sequential number (T001, T002, T003...) in execution order
+3. **[P] marker**: Include ONLY if task is parallelizable (different files, no dependencies on incomplete tasks)
+4. **[Story] label**: REQUIRED for user story phase tasks only
+   - Format: [US1], [US2], [US3], etc. (maps to user stories from spec.md)
+   - Setup phase: NO story label
+   - Foundational phase: NO story label  
+   - User Story phases: MUST have story label
+   - Polish phase: NO story label
+5. **Description**: Clear action with exact file path
+
+**Examples**:
+
+- ✅ CORRECT: `- [ ] T001 Create project structure per implementation plan`
+- ✅ CORRECT: `- [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py`
+- ✅ CORRECT: `- [ ] T012 [P] [US1] Create User model in src/models/user.py`
+- ✅ CORRECT: `- [ ] T014 [US1] Implement UserService in src/services/user_service.py`
+- ❌ WRONG: `- [ ] Create User model` (missing ID and Story label)
+- ❌ WRONG: `T001 [US1] Create model` (missing checkbox)
+- ❌ WRONG: `- [ ] [US1] Create User model` (missing Task ID)
+- ❌ WRONG: `- [ ] T001 [US1] Create model` (missing file path)
+
+### Task Organization
+
+1. **From User Stories (spec.md)** - PRIMARY ORGANIZATION:
+   - Each user story (P1, P2, P3...) gets its own phase
+   - Map all related components to their story:
+     - Models needed for that story
+     - Services needed for that story
+     - Interfaces/UI needed for that story
+     - If tests requested: Tests specific to that story
+   - Mark story dependencies (most stories should be independent)
+
+2. **From Contracts**:
+   - Map each interface contract → to the user story it serves
+   - If tests requested: Each interface contract → contract test task [P] before implementation in that story's phase
+
+3. **From Data Model**:
+   - Map each entity to the user story(ies) that need it
+   - If entity serves multiple stories: Put in earliest story or Setup phase
+   - Relationships → service layer tasks in appropriate story phase
+
+4. **From Setup/Infrastructure**:
+   - Shared infrastructure → Setup phase (Phase 1)
+   - Foundational/blocking tasks → Foundational phase (Phase 2)
+   - Story-specific setup → within that story's phase
+
+### Phase Structure
+
+- **Phase 1**: Setup (project initialization)
+- **Phase 2**: Foundational (blocking prerequisites - MUST complete before user stories)
+- **Phase 3+**: User Stories in priority order (P1, P2, P3...)
+  - Within each story: Tests (if requested) → Models → Services → Endpoints → Integration
+  - Each phase should be a complete, independently testable increment
+- **Final Phase**: Polish & Cross-Cutting Concerns

.github/agents/speckit.taskstoissues.agent.md

@@ -0,0 +1,30 @@
+---
+description: Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts.
+tools: ['github/github-mcp-server/issue_write']
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+1. From the executed script, extract the path to **tasks**.
+1. Get the Git remote by running:
+
+```bash
+git config --get remote.origin.url
+```
+
+> [!CAUTION]
+> ONLY PROCEED TO NEXT STEPS IF THE REMOTE IS A GITHUB URL
+
+1. For each task in the list, use the GitHub MCP server to create a new issue in the repository that is representative of the Git remote.
+
+> [!CAUTION]
+> UNDER NO CIRCUMSTANCES EVER CREATE ISSUES IN REPOSITORIES THAT DO NOT MATCH THE REMOTE URL

.github/prompts/speckit.analyze.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.analyze
+---

.github/prompts/speckit.checklist.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.checklist
+---

.github/prompts/speckit.clarify.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.clarify
+---

.github/prompts/speckit.constitution.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.constitution
+---

.github/prompts/speckit.implement.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.implement
+---

.github/prompts/speckit.plan.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.plan
+---

.github/prompts/speckit.specify.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.specify
+---

.github/prompts/speckit.tasks.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.tasks
+---

.github/prompts/speckit.taskstoissues.prompt.md

@@ -0,0 +1,3 @@
+---
+agent: speckit.taskstoissues
+---

.github/workflows/ci-breaking-changes.yaml

@@ -16,8 +16,6 @@ env:
 
 permissions:
   contents: read
-  pull-requests: write
-  checks: write
 
 jobs:
   changed-files-check:
@@ -584,182 +582,16 @@ jobs:
             echo "::warning::REST Metadata API analysis tool error - continuing workflow"
           fi
 
-      - name: Comment API Changes on PR
+      - name: Upload breaking changes report
         if: always()
-        uses: actions/github-script@v7
+        uses: actions/upload-artifact@v4
         with:
-          script: |
-            const fs = require('fs');
-            let hasChanges = false;
-            let comment = '';
-
-            try {
-              if (fs.existsSync('graphql-schema-diff.md')) {
-                const graphqlDiff = fs.readFileSync('graphql-schema-diff.md', 'utf8');
-                if (graphqlDiff.trim()) {
-                  if (!hasChanges) {
-                    comment = '## 📊 API Changes Report\n\n';
-                    hasChanges = true;
-                  }
-                  comment += '### GraphQL Schema Changes\n' + graphqlDiff + '\n\n';
-                }
-              }
-
-              if (fs.existsSync('graphql-metadata-diff.md')) {
-                const graphqlMetadataDiff = fs.readFileSync('graphql-metadata-diff.md', 'utf8');
-                if (graphqlMetadataDiff.trim()) {
-                  if (!hasChanges) {
-                    comment = '## 📊 API Changes Report\n\n';
-                    hasChanges = true;
-                  }
-                  comment += '### GraphQL Metadata Schema Changes\n' + graphqlMetadataDiff + '\n\n';
-                }
-              }
-
-              if (fs.existsSync('rest-api-diff.md')) {
-                const restDiff = fs.readFileSync('rest-api-diff.md', 'utf8');
-                if (restDiff.trim()) {
-                  if (!hasChanges) {
-                    comment = '## 📊 API Changes Report\n\n';
-                    hasChanges = true;
-                  }
-                  comment += restDiff + '\n\n';
-                }
-              }
-
-              if (fs.existsSync('rest-metadata-api-diff.md')) {
-                const metadataDiff = fs.readFileSync('rest-metadata-api-diff.md', 'utf8');
-                if (metadataDiff.trim()) {
-                  if (!hasChanges) {
-                    comment = '## 📊 API Changes Report\n\n';
-                    hasChanges = true;
-                  }
-                  comment += metadataDiff + '\n\n';
-                }
-              }
-
-              // Only post comment if there are changes
-              if (hasChanges) {
-                // Add branch state information only if there were conflicts
-                const branchState = process.env.BRANCH_STATE || 'unknown';
-                let branchStateNote = '';
-
-                if (branchState === 'conflicts') {
-                  branchStateNote = '\n\n⚠️ **Note**: Could not merge with `main` due to conflicts. This comparison shows changes between the current branch and `main` as separate states.\n';
-                }
-                // Check if there are any breaking changes detected
-                let hasBreakingChanges = false;
-                let breakingChangeNote = '';
-
-                // Check for breaking changes in any of the diff files
-                if (fs.existsSync('rest-api-diff.md')) {
-                  const restDiff = fs.readFileSync('rest-api-diff.md', 'utf8');
-                  if (restDiff.includes('Breaking Changes') || restDiff.includes('🚨') ||
-                      restDiff.includes('Removed Endpoints') || restDiff.includes('Changed Operations')) {
-                    hasBreakingChanges = true;
-                  }
-                }
-
-                if (fs.existsSync('rest-metadata-api-diff.md')) {
-                  const metadataDiff = fs.readFileSync('rest-metadata-api-diff.md', 'utf8');
-                  if (metadataDiff.includes('Breaking Changes') || metadataDiff.includes('🚨') ||
-                      metadataDiff.includes('Removed Endpoints') || metadataDiff.includes('Changed Operations')) {
-                    hasBreakingChanges = true;
-                  }
-                }
-
-                // Also check GraphQL changes for breaking changes indicators
-                if (fs.existsSync('graphql-schema-diff.md')) {
-                  const graphqlDiff = fs.readFileSync('graphql-schema-diff.md', 'utf8');
-                  if (graphqlDiff.includes('Breaking changes') || graphqlDiff.includes('BREAKING')) {
-                    hasBreakingChanges = true;
-                  }
-                }
-
-                if (fs.existsSync('graphql-metadata-diff.md')) {
-                  const graphqlMetadataDiff = fs.readFileSync('graphql-metadata-diff.md', 'utf8');
-                  if (graphqlMetadataDiff.includes('Breaking changes') || graphqlMetadataDiff.includes('BREAKING')) {
-                    hasBreakingChanges = true;
-                  }
-                }
-
-                // Check PR title for "breaking"
-                const prTitle = ${{ toJSON(github.event.pull_request.title) }};
-                const titleContainsBreaking = prTitle.toLowerCase().includes('breaking');
-
-                if (hasBreakingChanges) {
-                  if (titleContainsBreaking) {
-                    breakingChangeNote = '\n\n## ✅ Breaking Change Protocol\n\n' +
-                      '**This PR title contains "breaking" and breaking changes were detected - the CI will fail as expected.**\n\n' +
-                      '📝 **Action Required**: Please add `BREAKING CHANGE:` to your commit message to trigger a major version bump.\n\n' +
-                      'Example:\n```\nfeat: add new API endpoint\n\nBREAKING CHANGE: removed deprecated field from User schema\n```';
-                  } else {
-                    breakingChangeNote = '\n\n## ⚠️ Breaking Change Protocol\n\n' +
-                      '**Breaking changes detected but PR title does not contain "breaking" - CI will pass but action needed.**\n\n' +
-                      '🔄 **Options**:\n' +
-                      '1. **If this IS a breaking change**: Add "breaking" to your PR title and add `BREAKING CHANGE:` to your commit message\n' +
-                      '2. **If this is NOT a breaking change**: The API diff tool may have false positives - please review carefully\n\n' +
-                      'For breaking changes, add to commit message:\n```\nfeat: add new API endpoint\n\nBREAKING CHANGE: removed deprecated field from User schema\n```';
-                  }
-                }
-
-                const COMMENT_MARKER = '<!-- API_CHANGES_REPORT -->';
-                const commentBody = COMMENT_MARKER + '\n' + comment + branchStateNote + '\n⚠️ **Please review these API changes carefully before merging.**' + breakingChangeNote;
-
-                // Get all comments to find existing API changes comment
-                const {data: comments} = await github.rest.issues.listComments({
-                  owner: context.repo.owner,
-                  repo: context.repo.repo,
-                  issue_number: context.issue.number,
-                });
-
-                // Find our existing comment
-                const botComment = comments.find(comment => comment.body.includes(COMMENT_MARKER));
-
-                if (botComment) {
-                  // Update existing comment
-                  await github.rest.issues.updateComment({
-                    owner: context.repo.owner,
-                    repo: context.repo.repo,
-                    comment_id: botComment.id,
-                    body: commentBody
-                  });
-                  console.log('Updated existing API changes comment');
-                } else {
-                  // Create new comment
-                  await github.rest.issues.createComment({
-                    issue_number: context.issue.number,
-                    owner: context.repo.owner,
-                    repo: context.repo.repo,
-                    body: commentBody
-                  });
-                  console.log('Created new API changes comment');
-                }
-              } else {
-                console.log('No API changes detected - skipping PR comment');
-
-                // Check if there's an existing comment to remove
-                const {data: comments} = await github.rest.issues.listComments({
-                  owner: context.repo.owner,
-                  repo: context.repo.repo,
-                  issue_number: context.issue.number,
-                });
-
-                const COMMENT_MARKER = '<!-- API_CHANGES_REPORT -->';
-                const botComment = comments.find(comment => comment.body.includes(COMMENT_MARKER));
-
-                if (botComment) {
-                  await github.rest.issues.deleteComment({
-                    owner: context.repo.owner,
-                    repo: context.repo.repo,
-                    comment_id: botComment.id,
-                  });
-                  console.log('Deleted existing API changes comment (no changes detected)');
-                }
-              }
-            } catch (error) {
-              console.log('Could not post comment:', error);
-            }
+          name: breaking-changes-report
+          path: |
+            *-diff.md
+            *-diff.json
+          if-no-files-found: ignore
+          retention-days: 3
 
       - name: Cleanup servers
         if: always()
@@ -771,16 +603,4 @@ jobs:
             kill $(cat /tmp/main-server.pid) || true
           fi
 
-      - name: Upload API specifications and diffs
-        if: always()
-        uses: actions/upload-artifact@v4
-        with:
-          name: api-specifications-and-diffs
-          path: |
-            /tmp/main-server.log
-            /tmp/current-server.log
-            *-api.json
-            *-schema-introspection.json
-            *-diff.md
-            *-diff.json
 

.github/workflows/ci-front.yaml

@@ -98,47 +98,47 @@ jobs:
         run: npx nx reset:env twenty-front
       - name: Run storybook tests
         run: npx nx storybook:test twenty-front --configuration=${{ matrix.storybook_scope }} --shard=${{ matrix.shard }}/${{ env.SHARD_COUNTER }}
-      - name: Rename coverage file
-        run: |
-          if [ -f "packages/twenty-front/coverage/storybook/coverage-final.json" ]; then
-            mv packages/twenty-front/coverage/storybook/coverage-final.json packages/twenty-front/coverage/storybook/coverage-shard-${{matrix.shard}}.json
-          else
-            echo "Error: coverage-final.json not found"
-            ls -la packages/twenty-front/coverage/storybook/ || echo "Coverage directory does not exist"
-            exit 1
-          fi
-      - name: Upload coverage artifact
-        uses: actions/upload-artifact@v4
-        with:
-          retention-days: 1
-          name: coverage-artifacts-${{ matrix.storybook_scope }}-${{ github.run_id }}-${{ matrix.shard }}
-          path: packages/twenty-front/coverage/storybook/coverage-shard-${{matrix.shard}}.json
-  merge-reports-and-check-coverage:
-    timeout-minutes: 30
-    runs-on: ubuntu-latest
-    needs: front-sb-test
-    env:
-      PATH_TO_COVERAGE: packages/twenty-front/coverage/storybook
-    strategy:
-      matrix:
-        storybook_scope: [modules, pages, performance]
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Install dependencies
-        uses: ./.github/actions/yarn-install
-      - uses: actions/download-artifact@v4
-        with:
-          pattern: coverage-artifacts-${{ matrix.storybook_scope }}-${{ github.run_id }}-*
-          merge-multiple: true
-          path: coverage-artifacts
-      - name: Merge coverage reports
-        run: |
-          mkdir -p ${{ env.PATH_TO_COVERAGE }}
-          npx nyc merge coverage-artifacts ${{ env.PATH_TO_COVERAGE }}/coverage-storybook.json
-      - name: Checking coverage
-        run: npx nx storybook:coverage twenty-front --checkCoverage=true --configuration=${{ matrix.storybook_scope }}
+      # - name: Rename coverage file
+      #   run: |
+      #     if [ -f "packages/twenty-front/coverage/storybook/coverage-final.json" ]; then
+      #       mv packages/twenty-front/coverage/storybook/coverage-final.json packages/twenty-front/coverage/storybook/coverage-shard-${{matrix.shard}}.json
+      #     else
+      #       echo "Error: coverage-final.json not found"
+      #       ls -la packages/twenty-front/coverage/storybook/ || echo "Coverage directory does not exist"
+      #       exit 1
+      #     fi
+      # - name: Upload coverage artifact
+      #   uses: actions/upload-artifact@v4
+      #   with:
+      #     retention-days: 1
+      #     name: coverage-artifacts-${{ matrix.storybook_scope }}-${{ github.run_id }}-${{ matrix.shard }}
+      #     path: packages/twenty-front/coverage/storybook/coverage-shard-${{matrix.shard}}.json
+  # merge-reports-and-check-coverage:
+  #   timeout-minutes: 30
+  #   runs-on: ubuntu-latest
+  #   needs: front-sb-test
+  #   env:
+  #     PATH_TO_COVERAGE: packages/twenty-front/coverage/storybook
+  #   strategy:
+  #     matrix:
+  #       storybook_scope: [modules, pages, performance]
+  #   steps:
+  #     - uses: actions/checkout@v4
+  #       with:
+  #         fetch-depth: 0
+  #     - name: Install dependencies
+  #       uses: ./.github/actions/yarn-install
+  #     - uses: actions/download-artifact@v4
+  #       with:
+  #         pattern: coverage-artifacts-${{ matrix.storybook_scope }}-${{ github.run_id }}-*
+  #         merge-multiple: true
+  #         path: coverage-artifacts
+  #     - name: Merge coverage reports
+  #       run: |
+  #         mkdir -p ${{ env.PATH_TO_COVERAGE }}
+  #         npx nyc merge coverage-artifacts ${{ env.PATH_TO_COVERAGE }}/coverage-storybook.json
+  #     - name: Checking coverage
+  #       run: npx nx storybook:coverage twenty-front --checkCoverage=true --configuration=${{ matrix.storybook_scope }}
   front-chromatic-deployment:
     timeout-minutes: 30
     if: false
@@ -171,6 +171,7 @@ jobs:
     timeout-minutes: 30
     runs-on: ubuntu-latest
     env:
+      NODE_OPTIONS: '--max-old-space-size=4096'
       TASK_CACHE_KEY: front-task-${{ matrix.task }}
     strategy:
       matrix:
@@ -228,12 +229,12 @@ jobs:
         run: npx nx reset:env twenty-front
       - name: Build frontend
         run: npx nx build twenty-front
-      - name: Upload frontend build artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: frontend-build
-          path: packages/twenty-front/build
-          retention-days: 1
+      # - name: Upload frontend build artifact
+      #   uses: actions/upload-artifact@v4
+      #   with:
+      #     name: frontend-build
+      #     path: packages/twenty-front/build
+      #     retention-days: 1
   e2e-test:
     runs-on: ubuntu-latest
     needs: [changed-files-check-e2e, front-build]
@@ -295,15 +296,18 @@ jobs:
           cp packages/twenty-front/.env.example packages/twenty-front/.env
           npx nx reset:env:e2e-testing-server twenty-server
 
-      - name: Download frontend build artifact
-        if: needs.front-build.result == 'success'
-        uses: actions/download-artifact@v4
-        with:
-          name: frontend-build
-          path: packages/twenty-front/build
+      # - name: Download frontend build artifact
+      #   if: needs.front-build.result == 'success'
+      #   uses: actions/download-artifact@v4
+      #   with:
+      #     name: frontend-build
+      #     path: packages/twenty-front/build
 
-      - name: Build frontend (if not available from front-build)
-        if: needs.front-build.result == 'skipped'
+      # - name: Build frontend (if not available from front-build)
+      #   if: needs.front-build.result == 'skipped'
+      #   run: NODE_ENV=production NODE_OPTIONS="--max-old-space-size=10240" npx nx build twenty-front
+
+      - name: Build frontend
         run: NODE_ENV=production NODE_OPTIONS="--max-old-space-size=10240" npx nx build twenty-front
 
       - name: Build server
@@ -335,12 +339,12 @@ jobs:
       - name: Run Playwright tests
         run: npx nx test twenty-e2e-testing
 
-      - uses: actions/upload-artifact@v4
-        if: always()
-        with:
-          name: playwright-report
-          path: packages/twenty-e2e-testing/run_results/
-          retention-days: 30
+      # - uses: actions/upload-artifact@v4
+      #   if: always()
+      #   with:
+      #     name: playwright-report
+      #     path: packages/twenty-e2e-testing/run_results/
+      #     retention-days: 30
 
   ci-front-status-check:
     if: always() && !cancelled()
@@ -351,7 +355,7 @@ jobs:
         changed-files-check,
         front-task,
         front-build,
-        merge-reports-and-check-coverage,
+        # merge-reports-and-check-coverage,
         front-sb-test,
         front-sb-build,
       ]

.github/workflows/ci-shared.yaml

@@ -23,6 +23,8 @@ jobs:
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 30
     runs-on: ubuntu-latest
+    env:
+      NODE_OPTIONS: '--max-old-space-size=4096'
     strategy:
       matrix:
         task: [lint, typecheck, test]

.github/workflows/ci-utils.yaml

@@ -9,10 +9,7 @@ on:
     types: [opened, synchronize, reopened, closed]
 
 permissions:
-  actions: write
   checks: write
-  contents: write
-  issues: write
   pull-requests: write
   statuses: write
 

.github/workflows/ci-zapier.yaml

@@ -0,0 +1,128 @@
+name: CI Zapier
+
+on:
+  pull_request:
+
+  merge_group:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+env:
+  SERVER_SETUP_CACHE_KEY: server-setup
+
+jobs:
+  changed-files-check:
+    uses: ./.github/workflows/changed-files.yaml
+    with:
+      files: |
+        packages/twenty-zapier/**
+        packages/twenty-server/**
+        !packages/twenty-zapier/package.json
+        !packages/twenty-zapier/CHANGELOG.md
+  server-setup:
+    needs: changed-files-check
+    if: needs.changed-files-check.outputs.any_changed == 'true'
+    timeout-minutes: 30
+    runs-on: ubuntu-latest-8-cores
+    services:
+      postgres:
+        image: twentycrm/twenty-postgres-spilo
+        env:
+          PGUSER_SUPERUSER: postgres
+          PGPASSWORD_SUPERUSER: postgres
+          ALLOW_NOSSL: 'true'
+          SPILO_PROVIDER: 'local'
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+      redis:
+        image: redis
+        ports:
+          - 6379:6379
+    steps:
+      - name: Fetch custom Github Actions and base branch history
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install dependencies
+        uses: ./.github/actions/yarn-install
+
+      - name: Build twenty-shared
+        run: npx nx build twenty-shared
+
+      - name: Server / Write .env
+        run: npx nx reset:env:e2e-testing-server twenty-server
+
+      - name: Server / Build
+        run: npx nx build twenty-server
+
+      - name: Create and setup database
+        run: |
+          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "default";'
+          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "test";'
+          npx nx run twenty-server:database:reset
+
+      - name: Server / Start
+        run: |
+          npx nx start twenty-server &
+          echo "Waiting for server to be ready..."
+          timeout 60 bash -c 'until curl -s http://localhost:3000/health; do sleep 2; done'
+
+      - name: Start worker
+        run: |
+          npx nx run twenty-server:worker &
+          echo "Worker started"
+
+      - name: Zapier / Build
+        run: npx nx build twenty-zapier
+
+      - name: Zapier / Run Tests
+        uses: ./.github/actions/nx-affected
+        with:
+          tag: scope:zapier
+          tasks: test
+
+  zapier-test:
+    needs: server-setup
+    if: needs.changed-files-check.outputs.any_changed == 'true'
+    timeout-minutes: 30
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        task: [lint, typecheck, validate]
+    steps:
+      - name: Cancel Previous Runs
+        uses: styfle/[email protected]
+        with:
+          access_token: ${{ github.token }}
+      - name: Fetch custom Github Actions and base branch history
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install dependencies
+        uses: ./.github/actions/yarn-install
+      - name: Build
+        run: npx nx build twenty-zapier
+      - name: Run ${{ matrix.task }} task
+        uses: ./.github/actions/nx-affected
+        with:
+          tag: scope:zapier
+          tasks: ${{ matrix.task }}
+  ci-zapier-status-check:
+    if: always() && !cancelled()
+    timeout-minutes: 5
+    runs-on: ubuntu-latest
+    needs: [changed-files-check, zapier-test]
+    steps:
+      - name: Fail job if any needs failed
+        if: contains(needs.*.result, 'failure')
+        run: exit 1

.github/workflows/claude.yml

@@ -87,7 +87,7 @@ jobs:
             exit 0
           fi
           ISSUE_NUMBER="${{ github.event.issue.number || github.event.pull_request.number }}"
-          ENCODED_BRANCH=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$BRANCH', safe=''))")
+          ENCODED_BRANCH=$(python3 -c "import urllib.parse, sys; print(urllib.parse.quote(sys.argv[1], safe=''))" "$BRANCH")
           PR_URL="https://github.com/${{ github.repository }}/compare/main...${ENCODED_BRANCH}?quick_pull=1"
           BODY="⚠️ Claude ran out of turns before creating a PR. Work has been pushed to [\`$BRANCH\`](https://github.com/${{ github.repository }}/tree/$ENCODED_BRANCH).\n\n[**Create PR →**]($PR_URL)"
           if [ -n "$ISSUE_NUMBER" ]; then
@@ -157,18 +157,11 @@ jobs:
                 "PG_DATABASE_URL": "postgres://postgres:postgres@localhost:5432/default"
               }
             }
-      - name: Post response to source issue
+      - name: Dispatch response to ci-privileged
         if: always()
-        uses: actions/github-script@v7
+        uses: peter-evans/repository-dispatch@v2
         with:
-          github-token: ${{ secrets.TWENTY_DISPATCH_TOKEN }}
-          script: |
-            const [owner, repo] = '${{ steps.prompt.outputs.repo }}'.split('/');
-            const issueNumber = parseInt('${{ steps.prompt.outputs.issue_number }}', 10);
-
-            await github.rest.issues.createComment({
-              owner,
-              repo,
-              issue_number: issueNumber,
-              body: `Claude finished processing this request. [See workflow run](${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId})`
-            });
+          token: ${{ secrets.CI_PRIVILEGED_DISPATCH_TOKEN }}
+          repository: twentyhq/ci-privileged
+          event-type: claude-cross-repo-response
+          client-payload: '{"repo": ${{ toJSON(steps.prompt.outputs.repo) }}, "issue_number": ${{ toJSON(steps.prompt.outputs.issue_number) }}, "run_id": ${{ toJSON(github.run_id) }}, "run_url": ${{ toJSON(format('{0}/{1}/actions/runs/{2}', github.server_url, github.repository, github.run_id)) }}}'

.github/workflows/i18n-qa-report.yaml

@@ -1,118 +0,0 @@
-# Weekly translation QA report using Crowdin's native QA checks
-
-name: 'Weekly Translation QA Report'
-
-permissions:
-  contents: write
-  pull-requests: write
-
-on:
-  schedule:
-    - cron: '0 9 * * 1' # Every Monday at 9am UTC
-  workflow_dispatch: # Allow manual trigger
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
-  cancel-in-progress: true
-
-jobs:
-  qa_report:
-    name: Generate QA Report
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Install dependencies
-        uses: ./.github/actions/yarn-install
-
-      - name: Build twenty-shared
-        run: npx nx build twenty-shared
-
-      - name: Generate QA report from Crowdin
-        id: generate_report
-        run: |
-          npx ts-node packages/twenty-utils/translation-qa-report.ts || true
-          if [ -f TRANSLATION_QA_REPORT.md ]; then
-            echo "report_generated=true" >> $GITHUB_OUTPUT
-            # Count critical issues (exclude spellcheck)
-            CRITICAL=$(grep -oP '⚠️\s+\K\d+' TRANSLATION_QA_REPORT.md 2>/dev/null || echo "0")
-            echo "critical_issues=$CRITICAL" >> $GITHUB_OUTPUT
-          else
-            echo "report_generated=false" >> $GITHUB_OUTPUT
-            echo "critical_issues=0" >> $GITHUB_OUTPUT
-          fi
-        env:
-          CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}
-
-      - name: Create QA branch and commit report
-        if: steps.generate_report.outputs.report_generated == 'true'
-        run: |
-          git config --global user.name 'github-actions'
-          git config --global user.email '[email protected]'
-
-          BRANCH_NAME="i18n-qa-report-$(date +%Y-%m-%d)"
-          git checkout -B $BRANCH_NAME
-
-          git add TRANSLATION_QA_REPORT.md
-          if ! git diff --staged --quiet --exit-code; then
-            git commit -m "docs: weekly translation QA report"
-            git push origin HEAD:$BRANCH_NAME --force
-            echo "BRANCH_NAME=$BRANCH_NAME" >> $GITHUB_ENV
-          else
-            echo "No changes to commit"
-            echo "BRANCH_NAME=" >> $GITHUB_ENV
-          fi
-
-      - name: Create pull request
-        if: steps.generate_report.outputs.report_generated == 'true' && env.BRANCH_NAME != ''
-        run: |
-          CRITICAL="${{ steps.generate_report.outputs.critical_issues }}"
-
-          BODY=$(cat <<EOF
-          ## Weekly Translation QA Report
-
-          **Critical issues (excluding spellcheck): $CRITICAL**
-
-          📊 **View in Crowdin**: https://twenty.crowdin.com/u/projects/1/all?filter=qa-issue
-
-          ### For AI-Assisted Fixing
-
-          Open this PR in Cursor and say:
-
-          > "Fix the translation QA issues using the Crowdin API"
-
-          The AI can help fix:
-          - ✅ Variables mismatch (missing/wrong placeholders)
-          - ✅ Escaped Unicode sequences
-          - ⚠️ Tags mismatch
-          - ⚠️ Empty translations
-
-          ### Available Scripts
-
-          \`\`\`bash
-          # View QA report
-          CROWDIN_PERSONAL_TOKEN=xxx npx ts-node packages/twenty-utils/translation-qa-report.ts
-
-          # Fix encoding issues automatically
-          CROWDIN_PERSONAL_TOKEN=xxx npx ts-node packages/twenty-utils/fix-crowdin-translations.ts
-          \`\`\`
-
-          ---
-          *Close without merging after issues are addressed*
-          EOF
-          )
-
-          EXISTING_PR=$(gh pr list --head $BRANCH_NAME --json number --jq '.[0].number' 2>/dev/null || echo "")
-
-          if [ -n "$EXISTING_PR" ]; then
-            gh pr edit $EXISTING_PR --body "$BODY"
-          else
-            gh pr create \
-              --base main \
-              --head $BRANCH_NAME \
-              --title "i18n: Translation QA Report ($CRITICAL critical issues)" \
-              --body "$BODY" || true
-          fi
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/post-ci-comments.yaml

@@ -0,0 +1,71 @@
+name: Post CI Comments
+
+on:
+  workflow_run:
+    workflows: ['GraphQL and OpenAPI Breaking Changes Detection']
+    types: [completed]
+
+permissions:
+  actions: read
+
+jobs:
+  dispatch-breaking-changes:
+    if: github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Get PR number from workflow run
+        id: pr-info
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const runId = context.payload.workflow_run.id;
+            const headSha = context.payload.workflow_run.head_sha;
+            const headBranch = context.payload.workflow_run.head_branch;
+            const headRepo = context.payload.workflow_run.head_repository;
+
+            // workflow_run.pull_requests is empty for fork PRs,
+            // so fall back to searching by head SHA
+            let pullRequests = context.payload.workflow_run.pull_requests;
+            let prNumber;
+
+            if (pullRequests && pullRequests.length > 0) {
+              prNumber = pullRequests[0].number;
+            } else {
+              core.info(`pull_requests is empty (likely a fork PR), searching by SHA ${headSha}`);
+              const owner = context.repo.owner;
+              const repo = context.repo.repo;
+              const headLabel = `${headRepo.owner.login}:${headBranch}`;
+
+              const { data: prs } = await github.rest.pulls.list({
+                owner,
+                repo,
+                state: 'open',
+                head: headLabel,
+                per_page: 1,
+              });
+
+              if (prs.length > 0) {
+                prNumber = prs[0].number;
+              }
+            }
+
+            if (!prNumber) {
+              core.info('No pull request found for this workflow run');
+              core.setOutput('has_pr', 'false');
+              return;
+            }
+
+            core.setOutput('pr_number', prNumber);
+            core.setOutput('run_id', runId);
+            core.setOutput('has_pr', 'true');
+            core.info(`PR #${prNumber}, Run ID: ${runId}`);
+
+      - name: Dispatch to ci-privileged
+        if: steps.pr-info.outputs.has_pr == 'true'
+        uses: peter-evans/repository-dispatch@v2
+        with:
+          token: ${{ secrets.CI_PRIVILEGED_DISPATCH_TOKEN }}
+          repository: twentyhq/ci-privileged
+          event-type: breaking-changes-report
+          client-payload: '{"pr_number": ${{ toJSON(steps.pr-info.outputs.pr_number) }}, "run_id": ${{ toJSON(steps.pr-info.outputs.run_id) }}, "repo": ${{ toJSON(github.repository) }}, "branch_state": ${{ toJSON(github.event.workflow_run.head_branch) }}}'

.github/workflows/preview-env-dispatch.yaml

@@ -2,13 +2,8 @@ name: 'Preview Environment Dispatch'
 
 permissions:
   contents: write
-  actions: write
-  pull-requests: read
 
 on:
-  # Using pull_request_target instead of pull_request to have access to secrets for external contributors
-  # Security note: This is safe because we're only using the repository-dispatch action with limited scope
-  # and not checking out or running any code from the external contributor's PR
   pull_request_target:
     types: [opened, synchronize, reopened, labeled]
     paths:
@@ -24,7 +19,19 @@ concurrency:
 
 jobs:
   trigger-preview:
-    if: github.event.action == 'opened' || github.event.action == 'synchronize' || github.event.action == 'reopened' || (github.event.action == 'labeled' && github.event.label.name == 'preview-app')
+    if: |
+      (github.event.action == 'labeled' && github.event.label.name == 'preview-app') ||
+      (
+        (
+          github.event.pull_request.author_association == 'MEMBER' ||
+          github.event.pull_request.author_association == 'OWNER' ||
+          github.event.pull_request.author_association == 'COLLABORATOR'
+        ) && (
+          github.event.action == 'opened' ||
+          github.event.action == 'synchronize' ||
+          github.event.action == 'reopened'
+        )
+      )
     timeout-minutes: 5
     runs-on: ubuntu-latest
     steps:
@@ -35,3 +42,11 @@ jobs:
           repository: ${{ github.repository }}
           event-type: preview-environment
           client-payload: '{"pr_number": "${{ github.event.pull_request.number }}", "pr_head_sha": "${{ github.event.pull_request.head.sha }}", "repo_full_name": "${{ github.repository }}"}'
+
+      - name: Dispatch to ci-privileged for PR comment
+        uses: peter-evans/repository-dispatch@v2
+        with:
+          token: ${{ secrets.CI_PRIVILEGED_DISPATCH_TOKEN }}
+          repository: twentyhq/ci-privileged
+          event-type: preview-env-url
+          client-payload: '{"pr_number": ${{ toJSON(github.event.pull_request.number) }}, "keepalive_dispatch_time": ${{ toJSON(github.event.pull_request.updated_at) }}, "repo": ${{ toJSON(github.repository) }}}'

.github/workflows/preview-env-keepalive.yaml

@@ -2,7 +2,6 @@ name: 'Preview Environment Keep Alive'
 
 permissions:
   contents: read
-  pull-requests: write
 
 on:
   repository_dispatch:
@@ -17,7 +16,7 @@ jobs:
         uses: actions/checkout@v4
         with:
           ref: ${{ github.event.client_payload.pr_head_sha }}
-      
+
       - name: Run compose setup
         run: |
           echo "Patching docker-compose.yml..."
@@ -25,17 +24,17 @@ jobs:
           yq eval 'del(.services.server.image)' -i packages/twenty-docker/docker-compose.yml
           yq eval '.services.server.build.context = "../../"' -i packages/twenty-docker/docker-compose.yml
           yq eval '.services.server.build.dockerfile = "./packages/twenty-docker/twenty/Dockerfile"' -i packages/twenty-docker/docker-compose.yml
-          
+
           yq eval 'del(.services.worker.image)' -i packages/twenty-docker/docker-compose.yml
           yq eval '.services.worker.build.context = "../../"' -i packages/twenty-docker/docker-compose.yml
           yq eval '.services.worker.build.dockerfile = "./packages/twenty-docker/twenty/Dockerfile"' -i packages/twenty-docker/docker-compose.yml
-          
+
           echo "Adding SIGN_IN_PREFILLED environment variable to server service..."
           yq eval '.services.server.environment.SIGN_IN_PREFILLED = "${SIGN_IN_PREFILLED}"' -i packages/twenty-docker/docker-compose.yml
-          
+
           echo "Setting up .env file..."
           cp packages/twenty-docker/.env.example packages/twenty-docker/.env
-          
+
           echo "Generating secrets..."
           echo "" >> packages/twenty-docker/.env
           echo "# === Randomly generated secrets ===" >> packages/twenty-docker/.env
@@ -46,24 +45,25 @@ jobs:
           cd packages/twenty-docker/
           docker compose build
         working-directory: ./
-      
+
       - name: Create Tunnel
         id: expose-tunnel
         uses: codetalkio/[email protected]
         with:
           service: bore.pub
           port: 3000
-      
+
       - name: Start services with correct SERVER_URL
+        env:
+          TUNNEL_URL: ${{ steps.expose-tunnel.outputs.tunnel-url }}
         run: |
           cd packages/twenty-docker/
-          
-          # Update the SERVER_URL with the tunnel URL
-          echo "Setting SERVER_URL to ${{ steps.expose-tunnel.outputs.tunnel-url }}"
+
+          echo "Setting SERVER_URL to $TUNNEL_URL"
           sed -i '/SERVER_URL=/d' .env
           echo "" >> .env
-          echo "SERVER_URL=${{ steps.expose-tunnel.outputs.tunnel-url }}" >> .env
-          
+          echo "SERVER_URL=$TUNNEL_URL" >> .env
+
           # Start the services
           echo "Docker compose up..."
           docker compose up -d || {
@@ -71,7 +71,7 @@ jobs:
               docker compose logs
               exit 1
           }
-          
+
           echo "Waiting for services to be ready..."
           count=0
           while [ ! $(docker inspect --format='{{.State.Health.Status}}' twenty-db-1) = "healthy" ] || [ ! $(docker inspect --format='{{.State.Health.Status}}' twenty-server-1) = "healthy" ]; do
@@ -84,7 +84,7 @@ jobs:
               fi
               echo "Still waiting for services... ($count/60)"
           done
-          
+
           echo "All services are up and running!"
         working-directory: ./
 
@@ -99,61 +99,33 @@ jobs:
           fi
         working-directory: ./
 
-      - name: Output tunnel URL to logs
+      - name: Output tunnel URL
+        env:
+          TUNNEL_URL: ${{ steps.expose-tunnel.outputs.tunnel-url }}
         run: |
           echo "✅ Preview Environment Ready!"
-          echo "🔗 Preview URL: ${{ steps.expose-tunnel.outputs.tunnel-url }}"
+          echo "🔗 Preview URL: $TUNNEL_URL"
           echo "⏱️ This environment will be available for 5 hours"
-      
-      - name: Post comment on PR
-        uses: actions/github-script@v6
+          echo "## 🚀 Preview Environment Ready!" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "Preview URL: $TUNNEL_URL" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "This environment will automatically shut down after 5 hours." >> "$GITHUB_STEP_SUMMARY"
+          echo "$TUNNEL_URL" > tunnel-url.txt
+
+      - name: Upload tunnel URL artifact
+        uses: actions/upload-artifact@v4
         with:
-          github-token: ${{secrets.GITHUB_TOKEN}}
-          script: |
-            const COMMENT_MARKER = '<!-- PR_PREVIEW_ENV -->';
-            const commentBody = `${COMMENT_MARKER}
-            🚀 **Preview Environment Ready!**
-            
-            Your preview environment is available at: ${{ steps.expose-tunnel.outputs.tunnel-url }}
-            
-            This environment will automatically shut down when the PR is closed or after 5 hours.`;
-            
-            // Get all comments
-            const {data: comments} = await github.rest.issues.listComments({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: ${{ github.event.client_payload.pr_number }},
-            });
-            
-            // Find our comment
-            const botComment = comments.find(comment => comment.body.includes(COMMENT_MARKER));
-            
-            if (botComment) {
-              // Update existing comment
-              await github.rest.issues.updateComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                comment_id: botComment.id,
-                body: commentBody
-              });
-              console.log('Updated existing comment');
-            } else {
-              // Create new comment
-              await github.rest.issues.createComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: ${{ github.event.client_payload.pr_number }},
-                body: commentBody
-              });
-              console.log('Created new comment');
-            }
-      
+          name: tunnel-url
+          path: tunnel-url.txt
+          retention-days: 1
+
       - name: Keep tunnel alive for 5 hours
         run: timeout 300m sleep 18000 # Stop on whichever we reach first (300m or 5hour sleep)
-      
+
       - name: Cleanup
         if: always()
         run: |
           cd packages/twenty-docker/
           docker compose down -v
-        working-directory: ./ 
+        working-directory: ./

.specify/memory/constitution.md

@@ -0,0 +1,268 @@
+<!--
+  Sync Impact Report
+  ==================
+  Version change: N/A → 1.0.0 (initial ratification)
+  Modified principles: N/A (all new)
+  Added sections:
+    - Core Principles (7 principles)
+    - Technology Stack & Architecture
+    - Development Workflow & Quality Gates
+    - Governance
+  Removed sections: N/A
+  Templates requiring updates:
+    - .specify/templates/plan-template.md ✅ (Constitution Check section
+      already present; gates align with principles)
+    - .specify/templates/spec-template.md ✅ (no constitution-specific
+      references needed; structure is compatible)
+    - .specify/templates/tasks-template.md ✅ (task categorization supports
+      testing, migration, and lint phases per principles)
+    - .specify/templates/checklist-template.md ✅ (generic; compatible)
+    - .specify/templates/agent-file-template.md ✅ (generic; compatible)
+  Follow-up TODOs: none
+-->
+
+# Twenty CRM Constitution
+
+## Core Principles
+
+### I. Strict TypeScript (NON-NEGOTIABLE)
+
+All code MUST use strict TypeScript with `noImplicitAny` enabled.
+
+- The `any` type is NEVER permitted. Use `unknown`, generics, or
+  explicit union types instead.
+- Use `type` for all type definitions. Use `interface` ONLY when
+  extending a third-party interface.
+- Use string literal unions (`'admin' | 'user' | 'guest'`) instead
+  of `enum`. Exception: GraphQL enums generated by codegen.
+- Generic type parameters MUST have descriptive names
+  (`TData`, `TResult`, not `T`, `U`).
+- Suffix component props types with `Props`
+  (e.g., `ButtonProps`, `RecordTableProps`).
+- Leverage type inference for obvious cases; explicitly annotate
+  when the type is ambiguous or when it serves as documentation.
+
+**Rationale**: Strict typing eliminates entire categories of runtime
+errors and makes refactoring safe across a large monorepo.
+
+### II. Functional Components & Named Exports
+
+All React components MUST be functional components. Class components
+are NEVER permitted.
+
+- Every module MUST use named exports exclusively. Default exports
+  are NEVER permitted.
+- Destructure props at the function signature level.
+- Prefer event handlers over `useEffect` for state updates triggered
+  by user actions.
+- Apply composition over inheritance: build complex UI by composing
+  smaller, single-responsibility components.
+- Extract complex logic into custom hooks; keep components focused
+  on rendering.
+- Use `memo` only for demonstrably expensive components; memoize
+  callbacks with `useCallback` when stable references are required.
+
+**Rationale**: Functional components with hooks are simpler to reason
+about, test, and compose. Named exports enable reliable tree-shaking
+and explicit dependency graphs.
+
+### III. Nx Monorepo Discipline
+
+The repository is an Nx workspace managed with Yarn 4. All packages
+live under `packages/`.
+
+- `twenty-shared` MUST be built before any dependent package.
+- Libraries MUST export through `index.ts` barrel files.
+- Internal imports MUST use the `@/` path alias (never relative
+  paths crossing package boundaries).
+- Import order: external libraries → internal (`@/`) → relative.
+- ALWAYS prefer `npx nx lint:diff-with-main <project>` over full
+  project lints. Use `--configuration=fix` for auto-fix.
+- File and directory names MUST be kebab-case with descriptive
+  suffixes (`.component.tsx`, `.service.ts`, `.entity.ts`,
+  `.dto.ts`, `.module.ts`, `.test.tsx`, `.spec.ts`).
+- Components MUST stay under 300 lines; services under 500 lines.
+  Split when approaching limits.
+
+**Rationale**: Consistent monorepo conventions enable fast CI,
+reliable caching, and predictable project navigation for all
+contributors.
+
+### IV. Behavior-Driven Testing
+
+Tests MUST validate user-visible behavior, not implementation
+details.
+
+- Follow the Arrange-Act-Assert (AAA) pattern in every test.
+- Use descriptive test names: `"should [behavior] when [condition]"`.
+- Query elements by user-visible attributes (text, roles, labels);
+  avoid test IDs unless no accessible alternative exists.
+- Use `@testing-library/user-event` for realistic interactions.
+- Target the test pyramid: 70% unit, 20% integration, 10% E2E.
+- Prefer single-file test execution
+  (`npx jest path/to/test --config=packages/PROJECT/jest.config.mjs`)
+  over full suite runs.
+- Clear mocks with `jest.clearAllMocks()` in `beforeEach`.
+- Frontend test files use `.test.ts(x)`; server test files use
+  `.spec.ts`.
+
+**Rationale**: Behavior-focused tests are resilient to refactoring,
+catch real regressions, and serve as living documentation of user
+expectations.
+
+### V. Database Migration Integrity
+
+Every change to a TypeORM entity MUST have a corresponding generated
+migration.
+
+- Generate migrations with:
+  ```
+  npx nx run twenty-server:typeorm migration:generate \
+    src/database/typeorm/core/migrations/common/[name] \
+    -d src/database/typeorm/core/core.datasource.ts
+  ```
+- Migration names MUST be descriptive and kebab-case
+  (e.g., `add-agent-turn-evaluation`).
+- Every migration MUST include both `up` and `down` logic.
+- Committed migrations MUST NEVER be deleted or rewritten.
+- Prefer TypeORM-generated schema diffs; manually adjust only for
+  data backfills or complex constraints.
+
+**Rationale**: Strict migration discipline ensures reproducible
+database states across environments and safe rollbacks.
+
+### VI. Unidirectional State Management
+
+Application state MUST flow in one direction: props down, events up.
+
+- Use Jotai for global state via Twenty's custom utilities:
+  `createAtomState`, `createAtomSelector`,
+  `createAtomFamilyState`.
+- Use the corresponding hooks: `useAtomState` (read+write),
+  `useAtomStateValue` (read-only), `useSetAtomState` (write-only).
+- Use `useState` for component-local state, but prefer Jotai atoms as default;
+- NEVER use `useReducer` nor `useRef` for state management.
+- Normalize complex data structures with lookup tables; avoid
+  deeply nested state.
+- GraphQL cache is managed by Apollo Client; do not duplicate
+  server state in Jotai atoms.
+
+**Rationale**: Unidirectional flow makes state changes predictable,
+debuggable, and testable.
+
+### VII. Code Clarity & Security First
+
+Code MUST be self-explanatory; security constraints MUST be applied
+before any formatting or display logic.
+
+- Variable and function names MUST NOT use abbreviations
+  (`user` not `u`, `fieldMetadata` not `fm`).
+- Comments MUST use short-form `//` only (no JSDoc `/** */` blocks).
+  Explain WHY (business logic), never WHAT (obvious code).
+  Multi-line comments use multiple `//` lines. ALWAYS Prefer better variable and function naming over comments, only use comments as a last resort option.
+- Use utility helpers from `twenty-shared`:
+  `isDefined()`, `isNonEmptyString()`, `isNonEmptyArray()` instead
+  of manual type guards.
+- ALWAYS use `isDefined()` instead of `if(!value)` or `if(value)`
+- Prefer long names over short ones if it helps clarifying the code.
+- Apply security processing before formatting
+  (e.g., sanitize → then format for CSV export).
+- Error handling MUST use proper error types with meaningful
+  messages and contextual logging.
+- Internationalization uses Lingui; translated strings MUST NEVER
+  be concatenated. English translations MUST be added first.
+
+**Rationale**: Readable code reduces onboarding time and review
+friction. Security-first processing prevents injection and data
+leakage vulnerabilities.
+
+## Technology Stack & Architecture
+
+The Twenty CRM is built on the following stack. All implementation
+decisions MUST align with these choices:
+
+| Layer        | Technology                                         |
+|--------------|----------------------------------------------------|
+| Frontend     | React 18, TypeScript, Jotai, Linaria, Vite         |
+| Backend      | NestJS, TypeORM, PostgreSQL, Redis, GraphQL Yoga    |
+| Monorepo     | Nx workspace, Yarn 4                               |
+| Email        | React Email (`twenty-emails`)                      |
+| Background   | BullMQ workers                                     |
+| Analytics    | ClickHouse (when enabled)                          |
+| E2E Testing  | Playwright                                         |
+| Unit Testing | Jest, React Testing Library                        |
+| i18n         | Lingui                                             |
+| Docs Website | Next.js (`twenty-website`)                         |
+
+**Package structure**:
+
+- `twenty-front` — React frontend application
+- `twenty-server` — NestJS backend API
+- `twenty-ui` — Shared UI component library
+- `twenty-shared` — Common types and utilities (build first)
+- `twenty-emails` — Email templates
+- `twenty-e2e-testing` — Playwright E2E tests
+- `twenty-website` — Documentation site
+- `twenty-zapier` — Zapier integration
+
+Backend architecture follows NestJS module conventions with
+TypeORM entities, GraphQL code-first resolvers, and Redis-backed
+caching and session management.
+
+## Development Workflow & Quality Gates
+
+Every change MUST pass these quality gates before merge:
+
+1. **Lint** — `npx nx lint:diff-with-main <project>` MUST report
+   zero errors. Always prefer diff-based linting.
+2. **Type Check** — `npx nx typecheck <project>` MUST pass with
+   zero errors.
+3. **Unit Tests** — Relevant test files MUST pass. New behavior
+   MUST have accompanying tests.
+4. **GraphQL Codegen** — After any GraphQL schema change, run
+   `npx nx run twenty-front:graphql:generate` (and the metadata
+   configuration variant). Generated types MUST be committed.
+5. **Migration** — If any `.entity.ts` file changed, a generated
+   migration MUST be included in the same changeset.
+6. **Build** — `npx nx build twenty-shared` MUST succeed first,
+   then `npx nx build <project>`.
+
+**CI environment note**: In GitHub Actions, run
+`bash packages/twenty-utils/setup-dev-env.sh` before any build,
+test, lint, or database operation. The script is idempotent.
+
+**Branching workflow**:
+
+- Feature branches branch from and merge into `main`.
+- Build each changeset incrementally: commit after each logical
+  unit of work.
+- Use `npx nx affected --target=<target>` to scope CI to changed
+  projects.
+
+## Governance
+
+This constitution is the authoritative source of engineering
+standards for the Twenty CRM project. It supersedes any conflicting
+guidance found elsewhere.
+
+**Amendment procedure**:
+
+1. Propose the change with a rationale and the affected principles.
+2. Update this file with the new or revised text.
+3. Increment the version following semantic versioning:
+   - MAJOR: Backward-incompatible principle removal or redefinition.
+   - MINOR: New principle or materially expanded guidance.
+   - PATCH: Clarification, wording, or typo fixes.
+4. Update `LAST_AMENDED_DATE` to the amendment date.
+5. Propagate changes to dependent templates in
+   `.specify/templates/` and to `.cursor/rules/` as needed.
+
+**Compliance**:
+
+- All code reviews MUST verify adherence to these principles.
+- Deviations MUST be justified in the PR description and tracked
+  in the Complexity Tracking table of the implementation plan.
+- Use `CLAUDE.md` and `.cursor/rules/` for runtime development
+  guidance that elaborates on these principles.
+
+**Version**: 1.0.0 | **Ratified**: 2026-03-05 | **Last Amended**: 2026-03-05

.specify/scripts/bash/check-prerequisites.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+
+# Consolidated prerequisite checking script
+#
+# This script provides unified prerequisite checking for Spec-Driven Development workflow.
+# It replaces the functionality previously spread across multiple scripts.
+#
+# Usage: ./check-prerequisites.sh [OPTIONS]
+#
+# OPTIONS:
+#   --json              Output in JSON format
+#   --require-tasks     Require tasks.md to exist (for implementation phase)
+#   --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+#   --paths-only        Only output path variables (no validation)
+#   --help, -h          Show help message
+#
+# OUTPUTS:
+#   JSON mode: {"FEATURE_DIR":"...", "AVAILABLE_DOCS":["..."]}
+#   Text mode: FEATURE_DIR:... \n AVAILABLE_DOCS: \n ✓/✗ file.md
+#   Paths only: REPO_ROOT: ... \n BRANCH: ... \n FEATURE_DIR: ... etc.
+
+set -e
+
+# Parse command line arguments
+JSON_MODE=false
+REQUIRE_TASKS=false
+INCLUDE_TASKS=false
+PATHS_ONLY=false
+
+for arg in "$@"; do
+    case "$arg" in
+        --json)
+            JSON_MODE=true
+            ;;
+        --require-tasks)
+            REQUIRE_TASKS=true
+            ;;
+        --include-tasks)
+            INCLUDE_TASKS=true
+            ;;
+        --paths-only)
+            PATHS_ONLY=true
+            ;;
+        --help|-h)
+            cat << 'EOF'
+Usage: check-prerequisites.sh [OPTIONS]
+
+Consolidated prerequisite checking for Spec-Driven Development workflow.
+
+OPTIONS:
+  --json              Output in JSON format
+  --require-tasks     Require tasks.md to exist (for implementation phase)
+  --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+  --paths-only        Only output path variables (no prerequisite validation)
+  --help, -h          Show this help message
+
+EXAMPLES:
+  # Check task prerequisites (plan.md required)
+  ./check-prerequisites.sh --json
+  
+  # Check implementation prerequisites (plan.md + tasks.md required)
+  ./check-prerequisites.sh --json --require-tasks --include-tasks
+  
+  # Get feature paths only (no validation)
+  ./check-prerequisites.sh --paths-only
+  
+EOF
+            exit 0
+            ;;
+        *)
+            echo "ERROR: Unknown option '$arg'. Use --help for usage information." >&2
+            exit 1
+            ;;
+    esac
+done
+
+# Source common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get feature paths and validate branch
+eval $(get_feature_paths)
+check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+
+# If paths-only mode, output paths and exit (support JSON + paths-only combined)
+if $PATHS_ONLY; then
+    if $JSON_MODE; then
+        # Minimal JSON paths payload (no validation performed)
+        printf '{"REPO_ROOT":"%s","BRANCH":"%s","FEATURE_DIR":"%s","FEATURE_SPEC":"%s","IMPL_PLAN":"%s","TASKS":"%s"}\n' \
+            "$REPO_ROOT" "$CURRENT_BRANCH" "$FEATURE_DIR" "$FEATURE_SPEC" "$IMPL_PLAN" "$TASKS"
+    else
+        echo "REPO_ROOT: $REPO_ROOT"
+        echo "BRANCH: $CURRENT_BRANCH"
+        echo "FEATURE_DIR: $FEATURE_DIR"
+        echo "FEATURE_SPEC: $FEATURE_SPEC"
+        echo "IMPL_PLAN: $IMPL_PLAN"
+        echo "TASKS: $TASKS"
+    fi
+    exit 0
+fi
+
+# Validate required directories and files
+if [[ ! -d "$FEATURE_DIR" ]]; then
+    echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
+    echo "Run /speckit.specify first to create the feature structure." >&2
+    exit 1
+fi
+
+if [[ ! -f "$IMPL_PLAN" ]]; then
+    echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
+    echo "Run /speckit.plan first to create the implementation plan." >&2
+    exit 1
+fi
+
+# Check for tasks.md if required
+if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then
+    echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2
+    echo "Run /speckit.tasks first to create the task list." >&2
+    exit 1
+fi
+
+# Build list of available documents
+docs=()
+
+# Always check these optional docs
+[[ -f "$RESEARCH" ]] && docs+=("research.md")
+[[ -f "$DATA_MODEL" ]] && docs+=("data-model.md")
+
+# Check contracts directory (only if it exists and has files)
+if [[ -d "$CONTRACTS_DIR" ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]; then
+    docs+=("contracts/")
+fi
+
+[[ -f "$QUICKSTART" ]] && docs+=("quickstart.md")
+
+# Include tasks.md if requested and it exists
+if $INCLUDE_TASKS && [[ -f "$TASKS" ]]; then
+    docs+=("tasks.md")
+fi
+
+# Output results
+if $JSON_MODE; then
+    # Build JSON array of documents
+    if [[ ${#docs[@]} -eq 0 ]]; then
+        json_docs="[]"
+    else
+        json_docs=$(printf '"%s",' "${docs[@]}")
+        json_docs="[${json_docs%,}]"
+    fi
+    
+    printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$FEATURE_DIR" "$json_docs"
+else
+    # Text output
+    echo "FEATURE_DIR:$FEATURE_DIR"
+    echo "AVAILABLE_DOCS:"
+    
+    # Show status of each potential document
+    check_file "$RESEARCH" "research.md"
+    check_file "$DATA_MODEL" "data-model.md"
+    check_dir "$CONTRACTS_DIR" "contracts/"
+    check_file "$QUICKSTART" "quickstart.md"
+    
+    if $INCLUDE_TASKS; then
+        check_file "$TASKS" "tasks.md"
+    fi
+fi

.specify/scripts/bash/common.sh

@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+# Common functions and variables for all scripts
+
+# Get repository root, with fallback for non-git repositories
+get_repo_root() {
+    if git rev-parse --show-toplevel >/dev/null 2>&1; then
+        git rev-parse --show-toplevel
+    else
+        # Fall back to script location for non-git repos
+        local script_dir="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+        (cd "$script_dir/../../.." && pwd)
+    fi
+}
+
+# Get current branch, with fallback for non-git repositories
+get_current_branch() {
+    # First check if SPECIFY_FEATURE environment variable is set
+    if [[ -n "${SPECIFY_FEATURE:-}" ]]; then
+        echo "$SPECIFY_FEATURE"
+        return
+    fi
+
+    # Then check git if available
+    if git rev-parse --abbrev-ref HEAD >/dev/null 2>&1; then
+        git rev-parse --abbrev-ref HEAD
+        return
+    fi
+
+    # For non-git repos, try to find the latest feature directory
+    local repo_root=$(get_repo_root)
+    local specs_dir="$repo_root/specs"
+
+    if [[ -d "$specs_dir" ]]; then
+        local latest_feature=""
+        local highest=0
+
+        for dir in "$specs_dir"/*; do
+            if [[ -d "$dir" ]]; then
+                local dirname=$(basename "$dir")
+                if [[ "$dirname" =~ ^([0-9]{3})- ]]; then
+                    local number=${BASH_REMATCH[1]}
+                    number=$((10#$number))
+                    if [[ "$number" -gt "$highest" ]]; then
+                        highest=$number
+                        latest_feature=$dirname
+                    fi
+                fi
+            fi
+        done
+
+        if [[ -n "$latest_feature" ]]; then
+            echo "$latest_feature"
+            return
+        fi
+    fi
+
+    echo "main"  # Final fallback
+}
+
+# Check if we have git available
+has_git() {
+    git rev-parse --show-toplevel >/dev/null 2>&1
+}
+
+check_feature_branch() {
+    local branch="$1"
+    local has_git_repo="$2"
+
+    # For non-git repos, we can't enforce branch naming but still provide output
+    if [[ "$has_git_repo" != "true" ]]; then
+        echo "[specify] Warning: Git repository not detected; skipped branch validation" >&2
+        return 0
+    fi
+
+    if [[ ! "$branch" =~ ^[0-9]{3}- ]]; then
+        echo "ERROR: Not on a feature branch. Current branch: $branch" >&2
+        echo "Feature branches should be named like: 001-feature-name" >&2
+        return 1
+    fi
+
+    return 0
+}
+
+get_feature_dir() { echo "$1/specs/$2"; }
+
+# Find feature directory by numeric prefix instead of exact branch match
+# This allows multiple branches to work on the same spec (e.g., 004-fix-bug, 004-add-feature)
+find_feature_dir_by_prefix() {
+    local repo_root="$1"
+    local branch_name="$2"
+    local specs_dir="$repo_root/specs"
+
+    # Extract numeric prefix from branch (e.g., "004" from "004-whatever")
+    if [[ ! "$branch_name" =~ ^([0-9]{3})- ]]; then
+        # If branch doesn't have numeric prefix, fall back to exact match
+        echo "$specs_dir/$branch_name"
+        return
+    fi
+
+    local prefix="${BASH_REMATCH[1]}"
+
+    # Search for directories in specs/ that start with this prefix
+    local matches=()
+    if [[ -d "$specs_dir" ]]; then
+        for dir in "$specs_dir"/"$prefix"-*; do
+            if [[ -d "$dir" ]]; then
+                matches+=("$(basename "$dir")")
+            fi
+        done
+    fi
+
+    # Handle results
+    if [[ ${#matches[@]} -eq 0 ]]; then
+        # No match found - return the branch name path (will fail later with clear error)
+        echo "$specs_dir/$branch_name"
+    elif [[ ${#matches[@]} -eq 1 ]]; then
+        # Exactly one match - perfect!
+        echo "$specs_dir/${matches[0]}"
+    else
+        # Multiple matches - this shouldn't happen with proper naming convention
+        echo "ERROR: Multiple spec directories found with prefix '$prefix': ${matches[*]}" >&2
+        echo "Please ensure only one spec directory exists per numeric prefix." >&2
+        echo "$specs_dir/$branch_name"  # Return something to avoid breaking the script
+    fi
+}
+
+get_feature_paths() {
+    local repo_root=$(get_repo_root)
+    local current_branch=$(get_current_branch)
+    local has_git_repo="false"
+
+    if has_git; then
+        has_git_repo="true"
+    fi
+
+    # Use prefix-based lookup to support multiple branches per spec
+    local feature_dir=$(find_feature_dir_by_prefix "$repo_root" "$current_branch")
+
+    cat <<EOF
+REPO_ROOT='$repo_root'
+CURRENT_BRANCH='$current_branch'
+HAS_GIT='$has_git_repo'
+FEATURE_DIR='$feature_dir'
+FEATURE_SPEC='$feature_dir/spec.md'
+IMPL_PLAN='$feature_dir/plan.md'
+TASKS='$feature_dir/tasks.md'
+RESEARCH='$feature_dir/research.md'
+DATA_MODEL='$feature_dir/data-model.md'
+QUICKSTART='$feature_dir/quickstart.md'
+CONTRACTS_DIR='$feature_dir/contracts'
+EOF
+}
+
+check_file() { [[ -f "$1" ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
+check_dir() { [[ -d "$1" && -n $(ls -A "$1" 2>/dev/null) ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
+

.specify/scripts/bash/create-new-feature.sh

@@ -0,0 +1,313 @@
+#!/usr/bin/env bash
+
+set -e
+
+JSON_MODE=false
+SHORT_NAME=""
+BRANCH_NUMBER=""
+ARGS=()
+i=1
+while [ $i -le $# ]; do
+    arg="${!i}"
+    case "$arg" in
+        --json) 
+            JSON_MODE=true 
+            ;;
+        --short-name)
+            if [ $((i + 1)) -gt $# ]; then
+                echo 'Error: --short-name requires a value' >&2
+                exit 1
+            fi
+            i=$((i + 1))
+            next_arg="${!i}"
+            # Check if the next argument is another option (starts with --)
+            if [[ "$next_arg" == --* ]]; then
+                echo 'Error: --short-name requires a value' >&2
+                exit 1
+            fi
+            SHORT_NAME="$next_arg"
+            ;;
+        --number)
+            if [ $((i + 1)) -gt $# ]; then
+                echo 'Error: --number requires a value' >&2
+                exit 1
+            fi
+            i=$((i + 1))
+            next_arg="${!i}"
+            if [[ "$next_arg" == --* ]]; then
+                echo 'Error: --number requires a value' >&2
+                exit 1
+            fi
+            BRANCH_NUMBER="$next_arg"
+            ;;
+        --help|-h) 
+            echo "Usage: $0 [--json] [--short-name <name>] [--number N] <feature_description>"
+            echo ""
+            echo "Options:"
+            echo "  --json              Output in JSON format"
+            echo "  --short-name <name> Provide a custom short name (2-4 words) for the branch"
+            echo "  --number N          Specify branch number manually (overrides auto-detection)"
+            echo "  --help, -h          Show this help message"
+            echo ""
+            echo "Examples:"
+            echo "  $0 'Add user authentication system' --short-name 'user-auth'"
+            echo "  $0 'Implement OAuth2 integration for API' --number 5"
+            exit 0
+            ;;
+        *) 
+            ARGS+=("$arg") 
+            ;;
+    esac
+    i=$((i + 1))
+done
+
+FEATURE_DESCRIPTION="${ARGS[*]}"
+if [ -z "$FEATURE_DESCRIPTION" ]; then
+    echo "Usage: $0 [--json] [--short-name <name>] [--number N] <feature_description>" >&2
+    exit 1
+fi
+
+# Trim whitespace and validate description is not empty (e.g., user passed only whitespace)
+FEATURE_DESCRIPTION=$(echo "$FEATURE_DESCRIPTION" | xargs)
+if [ -z "$FEATURE_DESCRIPTION" ]; then
+    echo "Error: Feature description cannot be empty or contain only whitespace" >&2
+    exit 1
+fi
+
+# Function to find the repository root by searching for existing project markers
+find_repo_root() {
+    local dir="$1"
+    while [ "$dir" != "/" ]; do
+        if [ -d "$dir/.git" ] || [ -d "$dir/.specify" ]; then
+            echo "$dir"
+            return 0
+        fi
+        dir="$(dirname "$dir")"
+    done
+    return 1
+}
+
+# Function to get highest number from specs directory
+get_highest_from_specs() {
+    local specs_dir="$1"
+    local highest=0
+    
+    if [ -d "$specs_dir" ]; then
+        for dir in "$specs_dir"/*; do
+            [ -d "$dir" ] || continue
+            dirname=$(basename "$dir")
+            number=$(echo "$dirname" | grep -o '^[0-9]\+' || echo "0")
+            number=$((10#$number))
+            if [ "$number" -gt "$highest" ]; then
+                highest=$number
+            fi
+        done
+    fi
+    
+    echo "$highest"
+}
+
+# Function to get highest number from git branches
+get_highest_from_branches() {
+    local highest=0
+    
+    # Get all branches (local and remote)
+    branches=$(git branch -a 2>/dev/null || echo "")
+    
+    if [ -n "$branches" ]; then
+        while IFS= read -r branch; do
+            # Clean branch name: remove leading markers and remote prefixes
+            clean_branch=$(echo "$branch" | sed 's/^[* ]*//; s|^remotes/[^/]*/||')
+            
+            # Extract feature number if branch matches pattern ###-*
+            if echo "$clean_branch" | grep -q '^[0-9]\{3\}-'; then
+                number=$(echo "$clean_branch" | grep -o '^[0-9]\{3\}' || echo "0")
+                number=$((10#$number))
+                if [ "$number" -gt "$highest" ]; then
+                    highest=$number
+                fi
+            fi
+        done <<< "$branches"
+    fi
+    
+    echo "$highest"
+}
+
+# Function to check existing branches (local and remote) and return next available number
+check_existing_branches() {
+    local specs_dir="$1"
+
+    # Fetch all remotes to get latest branch info (suppress errors if no remotes)
+    git fetch --all --prune 2>/dev/null || true
+
+    # Get highest number from ALL branches (not just matching short name)
+    local highest_branch=$(get_highest_from_branches)
+
+    # Get highest number from ALL specs (not just matching short name)
+    local highest_spec=$(get_highest_from_specs "$specs_dir")
+
+    # Take the maximum of both
+    local max_num=$highest_branch
+    if [ "$highest_spec" -gt "$max_num" ]; then
+        max_num=$highest_spec
+    fi
+
+    # Return next number
+    echo $((max_num + 1))
+}
+
+# Function to clean and format a branch name
+clean_branch_name() {
+    local name="$1"
+    echo "$name" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//'
+}
+
+# Resolve repository root. Prefer git information when available, but fall back
+# to searching for repository markers so the workflow still functions in repositories that
+# were initialised with --no-git.
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if git rev-parse --show-toplevel >/dev/null 2>&1; then
+    REPO_ROOT=$(git rev-parse --show-toplevel)
+    HAS_GIT=true
+else
+    REPO_ROOT="$(find_repo_root "$SCRIPT_DIR")"
+    if [ -z "$REPO_ROOT" ]; then
+        echo "Error: Could not determine repository root. Please run this script from within the repository." >&2
+        exit 1
+    fi
+    HAS_GIT=false
+fi
+
+cd "$REPO_ROOT"
+
+SPECS_DIR="$REPO_ROOT/specs"
+mkdir -p "$SPECS_DIR"
+
+# Function to generate branch name with stop word filtering and length filtering
+generate_branch_name() {
+    local description="$1"
+    
+    # Common stop words to filter out
+    local stop_words="^(i|a|an|the|to|for|of|in|on|at|by|with|from|is|are|was|were|be|been|being|have|has|had|do|does|did|will|would|should|could|can|may|might|must|shall|this|that|these|those|my|your|our|their|want|need|add|get|set)$"
+    
+    # Convert to lowercase and split into words
+    local clean_name=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/ /g')
+    
+    # Filter words: remove stop words and words shorter than 3 chars (unless they're uppercase acronyms in original)
+    local meaningful_words=()
+    for word in $clean_name; do
+        # Skip empty words
+        [ -z "$word" ] && continue
+        
+        # Keep words that are NOT stop words AND (length >= 3 OR are potential acronyms)
+        if ! echo "$word" | grep -qiE "$stop_words"; then
+            if [ ${#word} -ge 3 ]; then
+                meaningful_words+=("$word")
+            elif echo "$description" | grep -q "\b${word^^}\b"; then
+                # Keep short words if they appear as uppercase in original (likely acronyms)
+                meaningful_words+=("$word")
+            fi
+        fi
+    done
+    
+    # If we have meaningful words, use first 3-4 of them
+    if [ ${#meaningful_words[@]} -gt 0 ]; then
+        local max_words=3
+        if [ ${#meaningful_words[@]} -eq 4 ]; then max_words=4; fi
+        
+        local result=""
+        local count=0
+        for word in "${meaningful_words[@]}"; do
+            if [ $count -ge $max_words ]; then break; fi
+            if [ -n "$result" ]; then result="$result-"; fi
+            result="$result$word"
+            count=$((count + 1))
+        done
+        echo "$result"
+    else
+        # Fallback to original logic if no meaningful words found
+        local cleaned=$(clean_branch_name "$description")
+        echo "$cleaned" | tr '-' '\n' | grep -v '^$' | head -3 | tr '\n' '-' | sed 's/-$//'
+    fi
+}
+
+# Generate branch name
+if [ -n "$SHORT_NAME" ]; then
+    # Use provided short name, just clean it up
+    BRANCH_SUFFIX=$(clean_branch_name "$SHORT_NAME")
+else
+    # Generate from description with smart filtering
+    BRANCH_SUFFIX=$(generate_branch_name "$FEATURE_DESCRIPTION")
+fi
+
+# Determine branch number
+if [ -z "$BRANCH_NUMBER" ]; then
+    if [ "$HAS_GIT" = true ]; then
+        # Check existing branches on remotes
+        BRANCH_NUMBER=$(check_existing_branches "$SPECS_DIR")
+    else
+        # Fall back to local directory check
+        HIGHEST=$(get_highest_from_specs "$SPECS_DIR")
+        BRANCH_NUMBER=$((HIGHEST + 1))
+    fi
+fi
+
+# Force base-10 interpretation to prevent octal conversion (e.g., 010 → 8 in octal, but should be 10 in decimal)
+FEATURE_NUM=$(printf "%03d" "$((10#$BRANCH_NUMBER))")
+BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
+
+# GitHub enforces a 244-byte limit on branch names
+# Validate and truncate if necessary
+MAX_BRANCH_LENGTH=244
+if [ ${#BRANCH_NAME} -gt $MAX_BRANCH_LENGTH ]; then
+    # Calculate how much we need to trim from suffix
+    # Account for: feature number (3) + hyphen (1) = 4 chars
+    MAX_SUFFIX_LENGTH=$((MAX_BRANCH_LENGTH - 4))
+    
+    # Truncate suffix at word boundary if possible
+    TRUNCATED_SUFFIX=$(echo "$BRANCH_SUFFIX" | cut -c1-$MAX_SUFFIX_LENGTH)
+    # Remove trailing hyphen if truncation created one
+    TRUNCATED_SUFFIX=$(echo "$TRUNCATED_SUFFIX" | sed 's/-$//')
+    
+    ORIGINAL_BRANCH_NAME="$BRANCH_NAME"
+    BRANCH_NAME="${FEATURE_NUM}-${TRUNCATED_SUFFIX}"
+    
+    >&2 echo "[specify] Warning: Branch name exceeded GitHub's 244-byte limit"
+    >&2 echo "[specify] Original: $ORIGINAL_BRANCH_NAME (${#ORIGINAL_BRANCH_NAME} bytes)"
+    >&2 echo "[specify] Truncated to: $BRANCH_NAME (${#BRANCH_NAME} bytes)"
+fi
+
+if [ "$HAS_GIT" = true ]; then
+    if ! git checkout -b "$BRANCH_NAME" 2>/dev/null; then
+        # Check if branch already exists
+        if git branch --list "$BRANCH_NAME" | grep -q .; then
+            >&2 echo "Error: Branch '$BRANCH_NAME' already exists. Please use a different feature name or specify a different number with --number."
+            exit 1
+        else
+            >&2 echo "Error: Failed to create git branch '$BRANCH_NAME'. Please check your git configuration and try again."
+            exit 1
+        fi
+    fi
+else
+    >&2 echo "[specify] Warning: Git repository not detected; skipped branch creation for $BRANCH_NAME"
+fi
+
+FEATURE_DIR="$SPECS_DIR/$BRANCH_NAME"
+mkdir -p "$FEATURE_DIR"
+
+TEMPLATE="$REPO_ROOT/.specify/templates/spec-template.md"
+SPEC_FILE="$FEATURE_DIR/spec.md"
+if [ -f "$TEMPLATE" ]; then cp "$TEMPLATE" "$SPEC_FILE"; else touch "$SPEC_FILE"; fi
+
+# Set the SPECIFY_FEATURE environment variable for the current session
+export SPECIFY_FEATURE="$BRANCH_NAME"
+
+if $JSON_MODE; then
+    printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s"}\n' "$BRANCH_NAME" "$SPEC_FILE" "$FEATURE_NUM"
+else
+    echo "BRANCH_NAME: $BRANCH_NAME"
+    echo "SPEC_FILE: $SPEC_FILE"
+    echo "FEATURE_NUM: $FEATURE_NUM"
+    echo "SPECIFY_FEATURE environment variable set to: $BRANCH_NAME"
+fi

.specify/scripts/bash/setup-plan.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+
+set -e
+
+# Parse command line arguments
+JSON_MODE=false
+ARGS=()
+
+for arg in "$@"; do
+    case "$arg" in
+        --json) 
+            JSON_MODE=true 
+            ;;
+        --help|-h) 
+            echo "Usage: $0 [--json]"
+            echo "  --json    Output results in JSON format"
+            echo "  --help    Show this help message"
+            exit 0 
+            ;;
+        *) 
+            ARGS+=("$arg") 
+            ;;
+    esac
+done
+
+# Get script directory and load common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get all paths and variables from common functions
+eval $(get_feature_paths)
+
+# Check if we're on a proper feature branch (only for git repos)
+check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+
+# Ensure the feature directory exists
+mkdir -p "$FEATURE_DIR"
+
+# Copy plan template if it exists
+TEMPLATE="$REPO_ROOT/.specify/templates/plan-template.md"
+if [[ -f "$TEMPLATE" ]]; then
+    cp "$TEMPLATE" "$IMPL_PLAN"
+    echo "Copied plan template to $IMPL_PLAN"
+else
+    echo "Warning: Plan template not found at $TEMPLATE"
+    # Create a basic plan file if template doesn't exist
+    touch "$IMPL_PLAN"
+fi
+
+# Output results
+if $JSON_MODE; then
+    printf '{"FEATURE_SPEC":"%s","IMPL_PLAN":"%s","SPECS_DIR":"%s","BRANCH":"%s","HAS_GIT":"%s"}\n' \
+        "$FEATURE_SPEC" "$IMPL_PLAN" "$FEATURE_DIR" "$CURRENT_BRANCH" "$HAS_GIT"
+else
+    echo "FEATURE_SPEC: $FEATURE_SPEC"
+    echo "IMPL_PLAN: $IMPL_PLAN" 
+    echo "SPECS_DIR: $FEATURE_DIR"
+    echo "BRANCH: $CURRENT_BRANCH"
+    echo "HAS_GIT: $HAS_GIT"
+fi
+

.specify/scripts/bash/update-agent-context.sh

@@ -0,0 +1,829 @@
+#!/usr/bin/env bash
+
+# Update agent context files with information from plan.md
+#
+# This script maintains AI agent context files by parsing feature specifications 
+# and updating agent-specific configuration files with project information.
+#
+# MAIN FUNCTIONS:
+# 1. Environment Validation
+#    - Verifies git repository structure and branch information
+#    - Checks for required plan.md files and templates
+#    - Validates file permissions and accessibility
+#
+# 2. Plan Data Extraction
+#    - Parses plan.md files to extract project metadata
+#    - Identifies language/version, frameworks, databases, and project types
+#    - Handles missing or incomplete specification data gracefully
+#
+# 3. Agent File Management
+#    - Creates new agent context files from templates when needed
+#    - Updates existing agent files with new project information
+#    - Preserves manual additions and custom configurations
+#    - Supports multiple AI agent formats and directory structures
+#
+# 4. Content Generation
+#    - Generates language-specific build/test commands
+#    - Creates appropriate project directory structures
+#    - Updates technology stacks and recent changes sections
+#    - Maintains consistent formatting and timestamps
+#
+# 5. Multi-Agent Support
+#    - Handles agent-specific file paths and naming conventions
+#    - Supports: Claude, Gemini, Copilot, Cursor, Qwen, opencode, Codex, Windsurf, Kilo Code, Auggie CLI, Roo Code, CodeBuddy CLI, Qoder CLI, Amp, SHAI, Kiro CLI, or Antigravity
+#    - Can update single agents or all existing agent files
+#    - Creates default Claude file if no agent files exist
+#
+# Usage: ./update-agent-context.sh [agent_type]
+# Agent types: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|kiro-cli|agy|bob|qodercli
+# Leave empty to update all existing agent files
+
+set -e
+
+# Enable strict error handling
+set -u
+set -o pipefail
+
+#==============================================================================
+# Configuration and Global Variables
+#==============================================================================
+
+# Get script directory and load common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get all paths and variables from common functions
+eval $(get_feature_paths)
+
+NEW_PLAN="$IMPL_PLAN"  # Alias for compatibility with existing code
+AGENT_TYPE="${1:-}"
+
+# Agent-specific file paths  
+CLAUDE_FILE="$REPO_ROOT/CLAUDE.md"
+GEMINI_FILE="$REPO_ROOT/GEMINI.md"
+COPILOT_FILE="$REPO_ROOT/.github/agents/copilot-instructions.md"
+CURSOR_FILE="$REPO_ROOT/.cursor/rules/specify-rules.mdc"
+QWEN_FILE="$REPO_ROOT/QWEN.md"
+AGENTS_FILE="$REPO_ROOT/AGENTS.md"
+WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md"
+KILOCODE_FILE="$REPO_ROOT/.kilocode/rules/specify-rules.md"
+AUGGIE_FILE="$REPO_ROOT/.augment/rules/specify-rules.md"
+ROO_FILE="$REPO_ROOT/.roo/rules/specify-rules.md"
+CODEBUDDY_FILE="$REPO_ROOT/CODEBUDDY.md"
+QODER_FILE="$REPO_ROOT/QODER.md"
+AMP_FILE="$REPO_ROOT/AGENTS.md"
+SHAI_FILE="$REPO_ROOT/SHAI.md"
+KIRO_FILE="$REPO_ROOT/AGENTS.md"
+AGY_FILE="$REPO_ROOT/.agent/rules/specify-rules.md"
+BOB_FILE="$REPO_ROOT/AGENTS.md"
+
+# Template file
+TEMPLATE_FILE="$REPO_ROOT/.specify/templates/agent-file-template.md"
+
+# Global variables for parsed plan data
+NEW_LANG=""
+NEW_FRAMEWORK=""
+NEW_DB=""
+NEW_PROJECT_TYPE=""
+
+#==============================================================================
+# Utility Functions
+#==============================================================================
+
+log_info() {
+    echo "INFO: $1"
+}
+
+log_success() {
+    echo "✓ $1"
+}
+
+log_error() {
+    echo "ERROR: $1" >&2
+}
+
+log_warning() {
+    echo "WARNING: $1" >&2
+}
+
+# Cleanup function for temporary files
+cleanup() {
+    local exit_code=$?
+    rm -f /tmp/agent_update_*_$$
+    rm -f /tmp/manual_additions_$$
+    exit $exit_code
+}
+
+# Set up cleanup trap
+trap cleanup EXIT INT TERM
+
+#==============================================================================
+# Validation Functions
+#==============================================================================
+
+validate_environment() {
+    # Check if we have a current branch/feature (git or non-git)
+    if [[ -z "$CURRENT_BRANCH" ]]; then
+        log_error "Unable to determine current feature"
+        if [[ "$HAS_GIT" == "true" ]]; then
+            log_info "Make sure you're on a feature branch"
+        else
+            log_info "Set SPECIFY_FEATURE environment variable or create a feature first"
+        fi
+        exit 1
+    fi
+    
+    # Check if plan.md exists
+    if [[ ! -f "$NEW_PLAN" ]]; then
+        log_error "No plan.md found at $NEW_PLAN"
+        log_info "Make sure you're working on a feature with a corresponding spec directory"
+        if [[ "$HAS_GIT" != "true" ]]; then
+            log_info "Use: export SPECIFY_FEATURE=your-feature-name or create a new feature first"
+        fi
+        exit 1
+    fi
+    
+    # Check if template exists (needed for new files)
+    if [[ ! -f "$TEMPLATE_FILE" ]]; then
+        log_warning "Template file not found at $TEMPLATE_FILE"
+        log_warning "Creating new agent files will fail"
+    fi
+}
+
+#==============================================================================
+# Plan Parsing Functions
+#==============================================================================
+
+extract_plan_field() {
+    local field_pattern="$1"
+    local plan_file="$2"
+    
+    grep "^\*\*${field_pattern}\*\*: " "$plan_file" 2>/dev/null | \
+        head -1 | \
+        sed "s|^\*\*${field_pattern}\*\*: ||" | \
+        sed 's/^[ \t]*//;s/[ \t]*$//' | \
+        grep -v "NEEDS CLARIFICATION" | \
+        grep -v "^N/A$" || echo ""
+}
+
+parse_plan_data() {
+    local plan_file="$1"
+    
+    if [[ ! -f "$plan_file" ]]; then
+        log_error "Plan file not found: $plan_file"
+        return 1
+    fi
+    
+    if [[ ! -r "$plan_file" ]]; then
+        log_error "Plan file is not readable: $plan_file"
+        return 1
+    fi
+    
+    log_info "Parsing plan data from $plan_file"
+    
+    NEW_LANG=$(extract_plan_field "Language/Version" "$plan_file")
+    NEW_FRAMEWORK=$(extract_plan_field "Primary Dependencies" "$plan_file")
+    NEW_DB=$(extract_plan_field "Storage" "$plan_file")
+    NEW_PROJECT_TYPE=$(extract_plan_field "Project Type" "$plan_file")
+    
+    # Log what we found
+    if [[ -n "$NEW_LANG" ]]; then
+        log_info "Found language: $NEW_LANG"
+    else
+        log_warning "No language information found in plan"
+    fi
+    
+    if [[ -n "$NEW_FRAMEWORK" ]]; then
+        log_info "Found framework: $NEW_FRAMEWORK"
+    fi
+    
+    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
+        log_info "Found database: $NEW_DB"
+    fi
+    
+    if [[ -n "$NEW_PROJECT_TYPE" ]]; then
+        log_info "Found project type: $NEW_PROJECT_TYPE"
+    fi
+}
+
+format_technology_stack() {
+    local lang="$1"
+    local framework="$2"
+    local parts=()
+    
+    # Add non-empty parts
+    [[ -n "$lang" && "$lang" != "NEEDS CLARIFICATION" ]] && parts+=("$lang")
+    [[ -n "$framework" && "$framework" != "NEEDS CLARIFICATION" && "$framework" != "N/A" ]] && parts+=("$framework")
+    
+    # Join with proper formatting
+    if [[ ${#parts[@]} -eq 0 ]]; then
+        echo ""
+    elif [[ ${#parts[@]} -eq 1 ]]; then
+        echo "${parts[0]}"
+    else
+        # Join multiple parts with " + "
+        local result="${parts[0]}"
+        for ((i=1; i<${#parts[@]}; i++)); do
+            result="$result + ${parts[i]}"
+        done
+        echo "$result"
+    fi
+}
+
+#==============================================================================
+# Template and Content Generation Functions
+#==============================================================================
+
+get_project_structure() {
+    local project_type="$1"
+    
+    if [[ "$project_type" == *"web"* ]]; then
+        echo "backend/\\nfrontend/\\ntests/"
+    else
+        echo "src/\\ntests/"
+    fi
+}
+
+get_commands_for_language() {
+    local lang="$1"
+    
+    case "$lang" in
+        *"Python"*)
+            echo "cd src && pytest && ruff check ."
+            ;;
+        *"Rust"*)
+            echo "cargo test && cargo clippy"
+            ;;
+        *"JavaScript"*|*"TypeScript"*)
+            echo "npm test \\&\\& npm run lint"
+            ;;
+        *)
+            echo "# Add commands for $lang"
+            ;;
+    esac
+}
+
+get_language_conventions() {
+    local lang="$1"
+    echo "$lang: Follow standard conventions"
+}
+
+create_new_agent_file() {
+    local target_file="$1"
+    local temp_file="$2"
+    local project_name="$3"
+    local current_date="$4"
+    
+    if [[ ! -f "$TEMPLATE_FILE" ]]; then
+        log_error "Template not found at $TEMPLATE_FILE"
+        return 1
+    fi
+    
+    if [[ ! -r "$TEMPLATE_FILE" ]]; then
+        log_error "Template file is not readable: $TEMPLATE_FILE"
+        return 1
+    fi
+    
+    log_info "Creating new agent context file from template..."
+    
+    if ! cp "$TEMPLATE_FILE" "$temp_file"; then
+        log_error "Failed to copy template file"
+        return 1
+    fi
+    
+    # Replace template placeholders
+    local project_structure
+    project_structure=$(get_project_structure "$NEW_PROJECT_TYPE")
+    
+    local commands
+    commands=$(get_commands_for_language "$NEW_LANG")
+    
+    local language_conventions
+    language_conventions=$(get_language_conventions "$NEW_LANG")
+    
+    # Perform substitutions with error checking using safer approach
+    # Escape special characters for sed by using a different delimiter or escaping
+    local escaped_lang=$(printf '%s\n' "$NEW_LANG" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+    local escaped_framework=$(printf '%s\n' "$NEW_FRAMEWORK" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+    local escaped_branch=$(printf '%s\n' "$CURRENT_BRANCH" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+    
+    # Build technology stack and recent change strings conditionally
+    local tech_stack
+    if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
+        tech_stack="- $escaped_lang + $escaped_framework ($escaped_branch)"
+    elif [[ -n "$escaped_lang" ]]; then
+        tech_stack="- $escaped_lang ($escaped_branch)"
+    elif [[ -n "$escaped_framework" ]]; then
+        tech_stack="- $escaped_framework ($escaped_branch)"
+    else
+        tech_stack="- ($escaped_branch)"
+    fi
+
+    local recent_change
+    if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
+        recent_change="- $escaped_branch: Added $escaped_lang + $escaped_framework"
+    elif [[ -n "$escaped_lang" ]]; then
+        recent_change="- $escaped_branch: Added $escaped_lang"
+    elif [[ -n "$escaped_framework" ]]; then
+        recent_change="- $escaped_branch: Added $escaped_framework"
+    else
+        recent_change="- $escaped_branch: Added"
+    fi
+
+    local substitutions=(
+        "s|\[PROJECT NAME\]|$project_name|"
+        "s|\[DATE\]|$current_date|"
+        "s|\[EXTRACTED FROM ALL PLAN.MD FILES\]|$tech_stack|"
+        "s|\[ACTUAL STRUCTURE FROM PLANS\]|$project_structure|g"
+        "s|\[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES\]|$commands|"
+        "s|\[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE\]|$language_conventions|"
+        "s|\[LAST 3 FEATURES AND WHAT THEY ADDED\]|$recent_change|"
+    )
+    
+    for substitution in "${substitutions[@]}"; do
+        if ! sed -i.bak -e "$substitution" "$temp_file"; then
+            log_error "Failed to perform substitution: $substitution"
+            rm -f "$temp_file" "$temp_file.bak"
+            return 1
+        fi
+    done
+    
+    # Convert \n sequences to actual newlines
+    newline=$(printf '\n')
+    sed -i.bak2 "s/\\\\n/${newline}/g" "$temp_file"
+
+    # Clean up backup files
+    rm -f "$temp_file.bak" "$temp_file.bak2"
+
+    # Prepend Cursor frontmatter for .mdc files so rules are auto-included
+    if [[ "$target_file" == *.mdc ]]; then
+        local frontmatter_file
+        frontmatter_file=$(mktemp) || return 1
+        printf '%s\n' "---" "description: Project Development Guidelines" "globs: [\"**/*\"]" "alwaysApply: true" "---" "" > "$frontmatter_file"
+        cat "$temp_file" >> "$frontmatter_file"
+        mv "$frontmatter_file" "$temp_file"
+    fi
+
+    return 0
+}
+
+
+
+
+update_existing_agent_file() {
+    local target_file="$1"
+    local current_date="$2"
+    
+    log_info "Updating existing agent context file..."
+    
+    # Use a single temporary file for atomic update
+    local temp_file
+    temp_file=$(mktemp) || {
+        log_error "Failed to create temporary file"
+        return 1
+    }
+    
+    # Process the file in one pass
+    local tech_stack=$(format_technology_stack "$NEW_LANG" "$NEW_FRAMEWORK")
+    local new_tech_entries=()
+    local new_change_entry=""
+    
+    # Prepare new technology entries
+    if [[ -n "$tech_stack" ]] && ! grep -q "$tech_stack" "$target_file"; then
+        new_tech_entries+=("- $tech_stack ($CURRENT_BRANCH)")
+    fi
+    
+    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]] && ! grep -q "$NEW_DB" "$target_file"; then
+        new_tech_entries+=("- $NEW_DB ($CURRENT_BRANCH)")
+    fi
+    
+    # Prepare new change entry
+    if [[ -n "$tech_stack" ]]; then
+        new_change_entry="- $CURRENT_BRANCH: Added $tech_stack"
+    elif [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]]; then
+        new_change_entry="- $CURRENT_BRANCH: Added $NEW_DB"
+    fi
+    
+    # Check if sections exist in the file
+    local has_active_technologies=0
+    local has_recent_changes=0
+    
+    if grep -q "^## Active Technologies" "$target_file" 2>/dev/null; then
+        has_active_technologies=1
+    fi
+    
+    if grep -q "^## Recent Changes" "$target_file" 2>/dev/null; then
+        has_recent_changes=1
+    fi
+    
+    # Process file line by line
+    local in_tech_section=false
+    local in_changes_section=false
+    local tech_entries_added=false
+    local changes_entries_added=false
+    local existing_changes_count=0
+    local file_ended=false
+    
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        # Handle Active Technologies section
+        if [[ "$line" == "## Active Technologies" ]]; then
+            echo "$line" >> "$temp_file"
+            in_tech_section=true
+            continue
+        elif [[ $in_tech_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
+            # Add new tech entries before closing the section
+            if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+                printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+                tech_entries_added=true
+            fi
+            echo "$line" >> "$temp_file"
+            in_tech_section=false
+            continue
+        elif [[ $in_tech_section == true ]] && [[ -z "$line" ]]; then
+            # Add new tech entries before empty line in tech section
+            if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+                printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+                tech_entries_added=true
+            fi
+            echo "$line" >> "$temp_file"
+            continue
+        fi
+        
+        # Handle Recent Changes section
+        if [[ "$line" == "## Recent Changes" ]]; then
+            echo "$line" >> "$temp_file"
+            # Add new change entry right after the heading
+            if [[ -n "$new_change_entry" ]]; then
+                echo "$new_change_entry" >> "$temp_file"
+            fi
+            in_changes_section=true
+            changes_entries_added=true
+            continue
+        elif [[ $in_changes_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
+            echo "$line" >> "$temp_file"
+            in_changes_section=false
+            continue
+        elif [[ $in_changes_section == true ]] && [[ "$line" == "- "* ]]; then
+            # Keep only first 2 existing changes
+            if [[ $existing_changes_count -lt 2 ]]; then
+                echo "$line" >> "$temp_file"
+                ((existing_changes_count++))
+            fi
+            continue
+        fi
+        
+        # Update timestamp
+        if [[ "$line" =~ \*\*Last\ updated\*\*:.*[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9] ]]; then
+            echo "$line" | sed "s/[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/$current_date/" >> "$temp_file"
+        else
+            echo "$line" >> "$temp_file"
+        fi
+    done < "$target_file"
+    
+    # Post-loop check: if we're still in the Active Technologies section and haven't added new entries
+    if [[ $in_tech_section == true ]] && [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+        printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+        tech_entries_added=true
+    fi
+    
+    # If sections don't exist, add them at the end of the file
+    if [[ $has_active_technologies -eq 0 ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+        echo "" >> "$temp_file"
+        echo "## Active Technologies" >> "$temp_file"
+        printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+        tech_entries_added=true
+    fi
+    
+    if [[ $has_recent_changes -eq 0 ]] && [[ -n "$new_change_entry" ]]; then
+        echo "" >> "$temp_file"
+        echo "## Recent Changes" >> "$temp_file"
+        echo "$new_change_entry" >> "$temp_file"
+        changes_entries_added=true
+    fi
+    
+    # Ensure Cursor .mdc files have YAML frontmatter for auto-inclusion
+    if [[ "$target_file" == *.mdc ]]; then
+        if ! head -1 "$temp_file" | grep -q '^---'; then
+            local frontmatter_file
+            frontmatter_file=$(mktemp) || { rm -f "$temp_file"; return 1; }
+            printf '%s\n' "---" "description: Project Development Guidelines" "globs: [\"**/*\"]" "alwaysApply: true" "---" "" > "$frontmatter_file"
+            cat "$temp_file" >> "$frontmatter_file"
+            mv "$frontmatter_file" "$temp_file"
+        fi
+    fi
+
+    # Move temp file to target atomically
+    if ! mv "$temp_file" "$target_file"; then
+        log_error "Failed to update target file"
+        rm -f "$temp_file"
+        return 1
+    fi
+
+    return 0
+}
+#==============================================================================
+# Main Agent File Update Function
+#==============================================================================
+
+update_agent_file() {
+    local target_file="$1"
+    local agent_name="$2"
+    
+    if [[ -z "$target_file" ]] || [[ -z "$agent_name" ]]; then
+        log_error "update_agent_file requires target_file and agent_name parameters"
+        return 1
+    fi
+    
+    log_info "Updating $agent_name context file: $target_file"
+    
+    local project_name
+    project_name=$(basename "$REPO_ROOT")
+    local current_date
+    current_date=$(date +%Y-%m-%d)
+    
+    # Create directory if it doesn't exist
+    local target_dir
+    target_dir=$(dirname "$target_file")
+    if [[ ! -d "$target_dir" ]]; then
+        if ! mkdir -p "$target_dir"; then
+            log_error "Failed to create directory: $target_dir"
+            return 1
+        fi
+    fi
+    
+    if [[ ! -f "$target_file" ]]; then
+        # Create new file from template
+        local temp_file
+        temp_file=$(mktemp) || {
+            log_error "Failed to create temporary file"
+            return 1
+        }
+        
+        if create_new_agent_file "$target_file" "$temp_file" "$project_name" "$current_date"; then
+            if mv "$temp_file" "$target_file"; then
+                log_success "Created new $agent_name context file"
+            else
+                log_error "Failed to move temporary file to $target_file"
+                rm -f "$temp_file"
+                return 1
+            fi
+        else
+            log_error "Failed to create new agent file"
+            rm -f "$temp_file"
+            return 1
+        fi
+    else
+        # Update existing file
+        if [[ ! -r "$target_file" ]]; then
+            log_error "Cannot read existing file: $target_file"
+            return 1
+        fi
+        
+        if [[ ! -w "$target_file" ]]; then
+            log_error "Cannot write to existing file: $target_file"
+            return 1
+        fi
+        
+        if update_existing_agent_file "$target_file" "$current_date"; then
+            log_success "Updated existing $agent_name context file"
+        else
+            log_error "Failed to update existing agent file"
+            return 1
+        fi
+    fi
+    
+    return 0
+}
+
+#==============================================================================
+# Agent Selection and Processing
+#==============================================================================
+
+update_specific_agent() {
+    local agent_type="$1"
+    
+    case "$agent_type" in
+        claude)
+            update_agent_file "$CLAUDE_FILE" "Claude Code"
+            ;;
+        gemini)
+            update_agent_file "$GEMINI_FILE" "Gemini CLI"
+            ;;
+        copilot)
+            update_agent_file "$COPILOT_FILE" "GitHub Copilot"
+            ;;
+        cursor-agent)
+            update_agent_file "$CURSOR_FILE" "Cursor IDE"
+            ;;
+        qwen)
+            update_agent_file "$QWEN_FILE" "Qwen Code"
+            ;;
+        opencode)
+            update_agent_file "$AGENTS_FILE" "opencode"
+            ;;
+        codex)
+            update_agent_file "$AGENTS_FILE" "Codex CLI"
+            ;;
+        windsurf)
+            update_agent_file "$WINDSURF_FILE" "Windsurf"
+            ;;
+        kilocode)
+            update_agent_file "$KILOCODE_FILE" "Kilo Code"
+            ;;
+        auggie)
+            update_agent_file "$AUGGIE_FILE" "Auggie CLI"
+            ;;
+        roo)
+            update_agent_file "$ROO_FILE" "Roo Code"
+            ;;
+        codebuddy)
+            update_agent_file "$CODEBUDDY_FILE" "CodeBuddy CLI"
+            ;;
+        qodercli)
+            update_agent_file "$QODER_FILE" "Qoder CLI"
+            ;;
+        amp)
+            update_agent_file "$AMP_FILE" "Amp"
+            ;;
+        shai)
+            update_agent_file "$SHAI_FILE" "SHAI"
+            ;;
+        kiro-cli)
+            update_agent_file "$KIRO_FILE" "Kiro CLI"
+            ;;
+        agy)
+            update_agent_file "$AGY_FILE" "Antigravity"
+            ;;
+        bob)
+            update_agent_file "$BOB_FILE" "IBM Bob"
+            ;;
+        generic)
+            log_info "Generic agent: no predefined context file. Use the agent-specific update script for your agent."
+            ;;
+        *)
+            log_error "Unknown agent type '$agent_type'"
+            log_error "Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|kiro-cli|agy|bob|qodercli|generic"
+            exit 1
+            ;;
+    esac
+}
+
+update_all_existing_agents() {
+    local found_agent=false
+    
+    # Check each possible agent file and update if it exists
+    if [[ -f "$CLAUDE_FILE" ]]; then
+        update_agent_file "$CLAUDE_FILE" "Claude Code"
+        found_agent=true
+    fi
+    
+    if [[ -f "$GEMINI_FILE" ]]; then
+        update_agent_file "$GEMINI_FILE" "Gemini CLI"
+        found_agent=true
+    fi
+    
+    if [[ -f "$COPILOT_FILE" ]]; then
+        update_agent_file "$COPILOT_FILE" "GitHub Copilot"
+        found_agent=true
+    fi
+    
+    if [[ -f "$CURSOR_FILE" ]]; then
+        update_agent_file "$CURSOR_FILE" "Cursor IDE"
+        found_agent=true
+    fi
+    
+    if [[ -f "$QWEN_FILE" ]]; then
+        update_agent_file "$QWEN_FILE" "Qwen Code"
+        found_agent=true
+    fi
+    
+    if [[ -f "$AGENTS_FILE" ]]; then
+        update_agent_file "$AGENTS_FILE" "Codex/opencode"
+        found_agent=true
+    fi
+    
+    if [[ -f "$WINDSURF_FILE" ]]; then
+        update_agent_file "$WINDSURF_FILE" "Windsurf"
+        found_agent=true
+    fi
+    
+    if [[ -f "$KILOCODE_FILE" ]]; then
+        update_agent_file "$KILOCODE_FILE" "Kilo Code"
+        found_agent=true
+    fi
+
+    if [[ -f "$AUGGIE_FILE" ]]; then
+        update_agent_file "$AUGGIE_FILE" "Auggie CLI"
+        found_agent=true
+    fi
+    
+    if [[ -f "$ROO_FILE" ]]; then
+        update_agent_file "$ROO_FILE" "Roo Code"
+        found_agent=true
+    fi
+
+    if [[ -f "$CODEBUDDY_FILE" ]]; then
+        update_agent_file "$CODEBUDDY_FILE" "CodeBuddy CLI"
+        found_agent=true
+    fi
+
+    if [[ -f "$SHAI_FILE" ]]; then
+        update_agent_file "$SHAI_FILE" "SHAI"
+        found_agent=true
+    fi
+
+    if [[ -f "$QODER_FILE" ]]; then
+        update_agent_file "$QODER_FILE" "Qoder CLI"
+        found_agent=true
+    fi
+
+    if [[ -f "$KIRO_FILE" ]]; then
+        update_agent_file "$KIRO_FILE" "Kiro CLI"
+        found_agent=true
+    fi
+
+    if [[ -f "$AGY_FILE" ]]; then
+        update_agent_file "$AGY_FILE" "Antigravity"
+        found_agent=true
+    fi
+    if [[ -f "$BOB_FILE" ]]; then
+        update_agent_file "$BOB_FILE" "IBM Bob"
+        found_agent=true
+    fi
+    
+    # If no agent files exist, create a default Claude file
+    if [[ "$found_agent" == false ]]; then
+        log_info "No existing agent files found, creating default Claude file..."
+        update_agent_file "$CLAUDE_FILE" "Claude Code"
+    fi
+}
+print_summary() {
+    echo
+    log_info "Summary of changes:"
+    
+    if [[ -n "$NEW_LANG" ]]; then
+        echo "  - Added language: $NEW_LANG"
+    fi
+    
+    if [[ -n "$NEW_FRAMEWORK" ]]; then
+        echo "  - Added framework: $NEW_FRAMEWORK"
+    fi
+    
+    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
+        echo "  - Added database: $NEW_DB"
+    fi
+    
+    echo
+
+    log_info "Usage: $0 [claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|amp|shai|kiro-cli|agy|bob|qodercli]"
+}
+
+#==============================================================================
+# Main Execution
+#==============================================================================
+
+main() {
+    # Validate environment before proceeding
+    validate_environment
+    
+    log_info "=== Updating agent context files for feature $CURRENT_BRANCH ==="
+    
+    # Parse the plan file to extract project information
+    if ! parse_plan_data "$NEW_PLAN"; then
+        log_error "Failed to parse plan data"
+        exit 1
+    fi
+    
+    # Process based on agent type argument
+    local success=true
+    
+    if [[ -z "$AGENT_TYPE" ]]; then
+        # No specific agent provided - update all existing agent files
+        log_info "No agent specified, updating all existing agent files..."
+        if ! update_all_existing_agents; then
+            success=false
+        fi
+    else
+        # Specific agent provided - update only that agent
+        log_info "Updating specific agent: $AGENT_TYPE"
+        if ! update_specific_agent "$AGENT_TYPE"; then
+            success=false
+        fi
+    fi
+    
+    # Print summary
+    print_summary
+    
+    if [[ "$success" == true ]]; then
+        log_success "Agent context update completed successfully"
+        exit 0
+    else
+        log_error "Agent context update completed with errors"
+        exit 1
+    fi
+}
+
+# Execute main function if script is run directly
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    main "$@"
+fi

.specify/templates/agent-file-template.md

@@ -0,0 +1,28 @@
+# [PROJECT NAME] Development Guidelines
+
+Auto-generated from all feature plans. Last updated: [DATE]
+
+## Active Technologies
+
+[EXTRACTED FROM ALL PLAN.MD FILES]
+
+## Project Structure
+
+```text
+[ACTUAL STRUCTURE FROM PLANS]
+```
+
+## Commands
+
+[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES]
+
+## Code Style
+
+[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE]
+
+## Recent Changes
+
+[LAST 3 FEATURES AND WHAT THEY ADDED]
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->

.specify/templates/checklist-template.md

@@ -0,0 +1,40 @@
+# [CHECKLIST TYPE] Checklist: [FEATURE NAME]
+
+**Purpose**: [Brief description of what this checklist covers]
+**Created**: [DATE]
+**Feature**: [Link to spec.md or relevant documentation]
+
+**Note**: This checklist is generated by the `/speckit.checklist` command based on feature context and requirements.
+
+<!-- 
+  ============================================================================
+  IMPORTANT: The checklist items below are SAMPLE ITEMS for illustration only.
+  
+  The /speckit.checklist command MUST replace these with actual items based on:
+  - User's specific checklist request
+  - Feature requirements from spec.md
+  - Technical context from plan.md
+  - Implementation details from tasks.md
+  
+  DO NOT keep these sample items in the generated checklist file.
+  ============================================================================
+-->
+
+## [Category 1]
+
+- [ ] CHK001 First checklist item with clear action
+- [ ] CHK002 Second checklist item
+- [ ] CHK003 Third checklist item
+
+## [Category 2]
+
+- [ ] CHK004 Another category item
+- [ ] CHK005 Item with specific criteria
+- [ ] CHK006 Final item in this category
+
+## Notes
+
+- Check items off as completed: `[x]`
+- Add comments or findings inline
+- Link to relevant resources or documentation
+- Items are numbered sequentially for easy reference

.specify/templates/constitution-template.md

@@ -0,0 +1,50 @@
+# [PROJECT_NAME] Constitution
+<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
+
+## Core Principles
+
+### [PRINCIPLE_1_NAME]
+<!-- Example: I. Library-First -->
+[PRINCIPLE_1_DESCRIPTION]
+<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
+
+### [PRINCIPLE_2_NAME]
+<!-- Example: II. CLI Interface -->
+[PRINCIPLE_2_DESCRIPTION]
+<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
+
+### [PRINCIPLE_3_NAME]
+<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
+[PRINCIPLE_3_DESCRIPTION]
+<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
+
+### [PRINCIPLE_4_NAME]
+<!-- Example: IV. Integration Testing -->
+[PRINCIPLE_4_DESCRIPTION]
+<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
+
+### [PRINCIPLE_5_NAME]
+<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
+[PRINCIPLE_5_DESCRIPTION]
+<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
+
+## [SECTION_2_NAME]
+<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
+
+[SECTION_2_CONTENT]
+<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
+
+## [SECTION_3_NAME]
+<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
+
+[SECTION_3_CONTENT]
+<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
+
+## Governance
+<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
+
+[GOVERNANCE_RULES]
+<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
+
+**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
+<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->

.specify/templates/plan-template.md

@@ -0,0 +1,104 @@
+# Implementation Plan: [FEATURE]
+
+**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
+**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
+
+**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/plan-template.md` for the execution workflow.
+
+## Summary
+
+[Extract from feature spec: primary requirement + technical approach from research]
+
+## Technical Context
+
+<!--
+  ACTION REQUIRED: Replace the content in this section with the technical details
+  for the project. The structure here is presented in advisory capacity to guide
+  the iteration process.
+-->
+
+**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]  
+**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]  
+**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]  
+**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]  
+**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
+**Project Type**: [e.g., library/cli/web-service/mobile-app/compiler/desktop-app or NEEDS CLARIFICATION]  
+**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]  
+**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]  
+**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+[Gates determined based on constitution file]
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/[###-feature]/
+├── plan.md              # This file (/speckit.plan command output)
+├── research.md          # Phase 0 output (/speckit.plan command)
+├── data-model.md        # Phase 1 output (/speckit.plan command)
+├── quickstart.md        # Phase 1 output (/speckit.plan command)
+├── contracts/           # Phase 1 output (/speckit.plan command)
+└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
+```
+
+### Source Code (repository root)
+<!--
+  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
+  for this feature. Delete unused options and expand the chosen structure with
+  real paths (e.g., apps/admin, packages/something). The delivered plan must
+  not include Option labels.
+-->
+
+```text
+# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
+src/
+├── models/
+├── services/
+├── cli/
+└── lib/
+
+tests/
+├── contract/
+├── integration/
+└── unit/
+
+# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
+backend/
+├── src/
+│   ├── models/
+│   ├── services/
+│   └── api/
+└── tests/
+
+frontend/
+├── src/
+│   ├── components/
+│   ├── pages/
+│   └── services/
+└── tests/
+
+# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
+api/
+└── [same as backend above]
+
+ios/ or android/
+└── [platform-specific structure: feature modules, UI flows, platform tests]
+```
+
+**Structure Decision**: [Document the selected structure and reference the real
+directories captured above]
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
+| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |

.specify/templates/spec-template.md

@@ -0,0 +1,115 @@
+# Feature Specification: [FEATURE NAME]
+
+**Feature Branch**: `[###-feature-name]`  
+**Created**: [DATE]  
+**Status**: Draft  
+**Input**: User description: "$ARGUMENTS"
+
+## User Scenarios & Testing *(mandatory)*
+
+<!--
+  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
+  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
+  you should still have a viable MVP (Minimum Viable Product) that delivers value.
+  
+  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
+  Think of each story as a standalone slice of functionality that can be:
+  - Developed independently
+  - Tested independently
+  - Deployed independently
+  - Demonstrated to users independently
+-->
+
+### User Story 1 - [Brief Title] (Priority: P1)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 2 - [Brief Title] (Priority: P2)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 3 - [Brief Title] (Priority: P3)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+[Add more user stories as needed, each with an assigned priority]
+
+### Edge Cases
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right edge cases.
+-->
+
+- What happens when [boundary condition]?
+- How does system handle [error scenario]?
+
+## Requirements *(mandatory)*
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right functional requirements.
+-->
+
+### Functional Requirements
+
+- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
+- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]  
+- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
+- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
+- **FR-005**: System MUST [behavior, e.g., "log all security events"]
+
+*Example of marking unclear requirements:*
+
+- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
+- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
+
+### Key Entities *(include if feature involves data)*
+
+- **[Entity 1]**: [What it represents, key attributes without implementation]
+- **[Entity 2]**: [What it represents, relationships to other entities]
+
+## Success Criteria *(mandatory)*
+
+<!--
+  ACTION REQUIRED: Define measurable success criteria.
+  These must be technology-agnostic and measurable.
+-->
+
+### Measurable Outcomes
+
+- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
+- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
+- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
+- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]

.specify/templates/tasks-template.md

@@ -0,0 +1,251 @@
+---
+
+description: "Task list template for feature implementation"
+---
+
+# Tasks: [FEATURE NAME]
+
+**Input**: Design documents from `/specs/[###-feature-name]/`
+**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
+
+**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.
+
+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+- **Single project**: `src/`, `tests/` at repository root
+- **Web app**: `backend/src/`, `frontend/src/`
+- **Mobile**: `api/src/`, `ios/src/` or `android/src/`
+- Paths shown below assume single project - adjust based on plan.md structure
+
+<!-- 
+  ============================================================================
+  IMPORTANT: The tasks below are SAMPLE TASKS for illustration purposes only.
+  
+  The /speckit.tasks command MUST replace these with actual tasks based on:
+  - User stories from spec.md (with their priorities P1, P2, P3...)
+  - Feature requirements from plan.md
+  - Entities from data-model.md
+  - Endpoints from contracts/
+  
+  Tasks MUST be organized by user story so each story can be:
+  - Implemented independently
+  - Tested independently
+  - Delivered as an MVP increment
+  
+  DO NOT keep these sample tasks in the generated tasks.md file.
+  ============================================================================
+-->
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Project initialization and basic structure
+
+- [ ] T001 Create project structure per implementation plan
+- [ ] T002 Initialize [language] project with [framework] dependencies
+- [ ] T003 [P] Configure linting and formatting tools
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+Examples of foundational tasks (adjust based on your project):
+
+- [ ] T004 Setup database schema and migrations framework
+- [ ] T005 [P] Implement authentication/authorization framework
+- [ ] T006 [P] Setup API routing and middleware structure
+- [ ] T007 Create base models/entities that all stories depend on
+- [ ] T008 Configure error handling and logging infrastructure
+- [ ] T009 Setup environment configuration management
+
+**Checkpoint**: Foundation ready - user story implementation can now begin in parallel
+
+---
+
+## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️
+
+> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
+
+- [ ] T010 [P] [US1] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T011 [P] [US1] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 1
+
+- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py
+- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py
+- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013)
+- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T016 [US1] Add validation and error handling
+- [ ] T017 [US1] Add logging for user story 1 operations
+
+**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently
+
+---
+
+## Phase 4: User Story 2 - [Title] (Priority: P2)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠️
+
+- [ ] T018 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T019 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 2
+
+- [ ] T020 [P] [US2] Create [Entity] model in src/models/[entity].py
+- [ ] T021 [US2] Implement [Service] in src/services/[service].py
+- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T023 [US2] Integrate with User Story 1 components (if needed)
+
+**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently
+
+---
+
+## Phase 5: User Story 3 - [Title] (Priority: P3)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠️
+
+- [ ] T024 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T025 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 3
+
+- [ ] T026 [P] [US3] Create [Entity] model in src/models/[entity].py
+- [ ] T027 [US3] Implement [Service] in src/services/[service].py
+- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py
+
+**Checkpoint**: All user stories should now be independently functional
+
+---
+
+[Add more user story phases as needed, following the same pattern]
+
+---
+
+## Phase N: Polish & Cross-Cutting Concerns
+
+**Purpose**: Improvements that affect multiple user stories
+
+- [ ] TXXX [P] Documentation updates in docs/
+- [ ] TXXX Code cleanup and refactoring
+- [ ] TXXX Performance optimization across all stories
+- [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/
+- [ ] TXXX Security hardening
+- [ ] TXXX Run quickstart.md validation
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies - can start immediately
+- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
+- **User Stories (Phase 3+)**: All depend on Foundational phase completion
+  - User stories can then proceed in parallel (if staffed)
+  - Or sequentially in priority order (P1 → P2 → P3)
+- **Polish (Final Phase)**: Depends on all desired user stories being complete
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
+- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable
+- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable
+
+### Within Each User Story
+
+- Tests (if included) MUST be written and FAIL before implementation
+- Models before services
+- Services before endpoints
+- Core implementation before integration
+- Story complete before moving to next priority
+
+### Parallel Opportunities
+
+- All Setup tasks marked [P] can run in parallel
+- All Foundational tasks marked [P] can run in parallel (within Phase 2)
+- Once Foundational phase completes, all user stories can start in parallel (if team capacity allows)
+- All tests for a user story marked [P] can run in parallel
+- Models within a story marked [P] can run in parallel
+- Different user stories can be worked on in parallel by different team members
+
+---
+
+## Parallel Example: User Story 1
+
+```bash
+# Launch all tests for User Story 1 together (if tests requested):
+Task: "Contract test for [endpoint] in tests/contract/test_[name].py"
+Task: "Integration test for [user journey] in tests/integration/test_[name].py"
+
+# Launch all models for User Story 1 together:
+Task: "Create [Entity1] model in src/models/[entity1].py"
+Task: "Create [Entity2] model in src/models/[entity2].py"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup
+2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
+3. Complete Phase 3: User Story 1
+4. **STOP and VALIDATE**: Test User Story 1 independently
+5. Deploy/demo if ready
+
+### Incremental Delivery
+
+1. Complete Setup + Foundational → Foundation ready
+2. Add User Story 1 → Test independently → Deploy/Demo (MVP!)
+3. Add User Story 2 → Test independently → Deploy/Demo
+4. Add User Story 3 → Test independently → Deploy/Demo
+5. Each story adds value without breaking previous stories
+
+### Parallel Team Strategy
+
+With multiple developers:
+
+1. Team completes Setup + Foundational together
+2. Once Foundational is done:
+   - Developer A: User Story 1
+   - Developer B: User Story 2
+   - Developer C: User Story 3
+3. Stories complete and integrate independently
+
+---
+
+## Notes
+
+- [P] tasks = different files, no dependencies
+- [Story] label maps task to specific user story for traceability
+- Each user story should be independently completable and testable
+- Verify tests fail before implementing
+- Commit after each task or logical group
+- Stop at any checkpoint to validate story independently
+- Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence

.vscode/settings.json

@@ -1,58 +1,70 @@
 {
-  "editor.formatOnSave": false,
-  "files.eol": "\n",
-  "files.insertFinalNewline": true,
-  "files.trimTrailingWhitespace": true,
-  "[typescript]": {
     "editor.formatOnSave": false,
-    "editor.codeActionsOnSave": {
-      "source.fixAll.eslint": "explicit",
-      "source.addMissingImports": "always",
-      "source.organizeImports": "always"
+    "files.eol": "\n",
+    "files.insertFinalNewline": true,
+    "files.trimTrailingWhitespace": true,
+    "[typescript]": {
+        "editor.formatOnSave": false,
+        "editor.codeActionsOnSave": {
+            "source.fixAll.eslint": "explicit",
+            "source.addMissingImports": "always",
+            "source.organizeImports": "always"
+        }
+    },
+    "[javascript]": {
+        "editor.formatOnSave": false,
+        "editor.codeActionsOnSave": {
+            "source.fixAll.eslint": "explicit",
+            "source.addMissingImports": "always",
+            "source.organizeImports": "always"
+        }
+    },
+    "[typescriptreact]": {
+        "editor.formatOnSave": false,
+        "editor.codeActionsOnSave": {
+            "source.fixAll.eslint": "explicit",
+            "source.addMissingImports": "always",
+            "source.organizeImports": "always"
+        }
+    },
+    "[json]": {
+        "editor.formatOnSave": true
+    },
+    "javascript.format.enable": false,
+    "javascript.preferences.importModuleSpecifier": "non-relative",
+    "typescript.format.enable": false,
+    "cSpell.enableFiletypes": [
+        "!javascript",
+        "!json",
+        "!typescript",
+        "!typescriptreact",
+        "md",
+        "mdx"
+    ],
+    "cSpell.words": [
+        "twentyhq"
+    ],
+    "typescript.preferences.importModuleSpecifier": "non-relative",
+    "search.exclude": {
+        "**/.yarn": true
+    },
+    "eslint.useFlatConfig": true,
+    "eslint.debug": true,
+    "files.associations": {
+        ".cursorrules": "markdown"
+    },
+    "jestrunner.codeLensSelector": "**/*.{test,spec,integration-spec}.{js,jsx,ts,tsx}",
+    "typescript.tsdk": "node_modules/typescript/lib",
+    "typescript.experimental.useTsgo": false,
+    "chat.promptFilesRecommendations": {
+        "speckit.constitution": true,
+        "speckit.specify": true,
+        "speckit.plan": true,
+        "speckit.tasks": true,
+        "speckit.implement": true
+    },
+    "chat.tools.terminal.autoApprove": {
+        ".specify/scripts/bash/": true,
+        ".specify/scripts/powershell/": true
     }
-  },
-  "[javascript]": {
-    "editor.formatOnSave": false,
-    "editor.codeActionsOnSave": {
-      "source.fixAll.eslint": "explicit",
-      "source.addMissingImports": "always",
-      "source.organizeImports": "always"
-    }
-  },
-  "[typescriptreact]": {
-    "editor.formatOnSave": false,
-    "editor.codeActionsOnSave": {
-      "source.fixAll.eslint": "explicit",
-      "source.addMissingImports": "always",
-      "source.organizeImports": "always"
-    }
-  },
-  "[json]": {
-    "editor.formatOnSave": true
-  },
-  "javascript.format.enable": false,
-  "javascript.preferences.importModuleSpecifier": "non-relative",
-  "typescript.format.enable": false,
-  "cSpell.enableFiletypes": [
-    "!javascript",
-    "!json",
-    "!typescript",
-    "!typescriptreact",
-    "md",
-    "mdx"
-  ],
-  "cSpell.words": [
-    "twentyhq"
-  ],
-  "typescript.preferences.importModuleSpecifier": "non-relative",
-  "search.exclude": {
-    "**/.yarn": true
-  },
-  "eslint.debug": true,
-  "files.associations": {
-    ".cursorrules": "markdown"
-  },
-  "jestrunner.codeLensSelector": "**/*.{test,spec,integration-spec}.{js,jsx,ts,tsx}",
-  "typescript.tsdk": "node_modules/typescript/lib",
-  "typescript.experimental.useTsgo": false
 }

.yarn/patches/@wyw-in-js-transform-npm-0.7.0-ba641dc99f.patch

@@ -0,0 +1,58 @@
+diff --git a/esm/cache.js b/esm/cache.js
+index 07cf6d7dd99effb9c3464b620ba67a7f445224f5..248bb527923499a6be8065ee7a3613b55819c58c 100644
+--- a/esm/cache.js
++++ b/esm/cache.js
+@@ -69,17 +69,20 @@ export class TransformCacheCollection {
+       this.invalidate(cacheName, filename);
+     });
+   }
+-  invalidateIfChanged(filename, content) {
++  invalidateIfChanged(filename, content, _visited) {
++    const visited = _visited || new Set();
++    if (visited.has(filename)) {
++      return false;
++    }
++    visited.add(filename);
+     const fileEntrypoint = this.get('entrypoints', filename);
+ 
+-    // We need to check all dependencies of the file
+-    // because they might have changed as well.
+     if (fileEntrypoint) {
+       for (const [, dependency] of fileEntrypoint.dependencies) {
+         const dependencyFilename = dependency.resolved;
+         if (dependencyFilename) {
+           const dependencyContent = fs.readFileSync(dependencyFilename, 'utf8');
+-          this.invalidateIfChanged(dependencyFilename, dependencyContent);
++          this.invalidateIfChanged(dependencyFilename, dependencyContent, visited);
+         }
+       }
+     }
+diff --git a/lib/cache.js b/lib/cache.js
+index 0762ed7d3c39b31000f7aa7d8156da15403c8e64..6955410cd3c9ec53cf7a01c8346abc4c47fff791 100644
+--- a/lib/cache.js
++++ b/lib/cache.js
+@@ -77,17 +77,20 @@ class TransformCacheCollection {
+       this.invalidate(cacheName, filename);
+     });
+   }
+-  invalidateIfChanged(filename, content) {
++  invalidateIfChanged(filename, content, _visited) {
++    const visited = _visited || new Set();
++    if (visited.has(filename)) {
++      return false;
++    }
++    visited.add(filename);
+     const fileEntrypoint = this.get('entrypoints', filename);
+ 
+-    // We need to check all dependencies of the file
+-    // because they might have changed as well.
+     if (fileEntrypoint) {
+       for (const [, dependency] of fileEntrypoint.dependencies) {
+         const dependencyFilename = dependency.resolved;
+         if (dependencyFilename) {
+           const dependencyContent = _nodeFs.default.readFileSync(dependencyFilename, 'utf8');
+-          this.invalidateIfChanged(dependencyFilename, dependencyContent);
++          this.invalidateIfChanged(dependencyFilename, dependencyContent, visited);
+         }
+       }
+     }

CLAUDE.md

@@ -90,7 +90,7 @@ npx nx run twenty-front:graphql:generate --configuration=metadata
 ## Architecture Overview
 
 ### Tech Stack
-- **Frontend**: React 18, TypeScript, Recoil (state management), Emotion (styling), Vite
+- **Frontend**: React 18, TypeScript, Jotai (state management), Linaria (styling), Vite
 - **Backend**: NestJS, TypeORM, PostgreSQL, Redis, GraphQL (with GraphQL Yoga)
 - **Monorepo**: Nx workspace managed with Yarn 4
 
@@ -138,7 +138,7 @@ packages/
 - Multi-line comments use multiple `//` lines, not `/** */`
 
 ### State Management
-- **Recoil** for global state: atoms for primitive state, selectors for derived state, atom families for dynamic collections
+- **Jotai** for global state: atoms for primitive state, selectors for derived state, atom families for dynamic collections
 - Component-specific state with React hooks (`useState`, `useReducer` for complex logic)
 - GraphQL cache managed by Apollo Client
 - Use functional state updates: `setState(prev => prev + 1)`
@@ -175,7 +175,7 @@ IMPORTANT: Use Context7 for code generation, setup or configuration steps, or li
 5. Run `graphql:generate` after any GraphQL schema changes
 
 ### Code Style Notes
-- Use **Emotion** for styling with styled-components pattern
+- Use **Linaria** for styling with zero-runtime CSS-in-JS (styled-components pattern)
 - Follow **Nx** workspace conventions for imports
 - Use **Lingui** for internationalization
 - Apply security first, then formatting (sanitize before format)

README.md

@@ -28,7 +28,7 @@ See:
 🚀 [Self-hosting](https://docs.twenty.com/developers/self-hosting/docker-compose)
 🖥️ [Local Setup](https://docs.twenty.com/developers/local-setup)
 
-# Does the world need another CRM?
+# Why Twenty
 
 We built Twenty for three reasons:
 
@@ -109,7 +109,7 @@ Below are a few features we have implemented to date:
 - [TypeScript](https://www.typescriptlang.org/)
 - [Nx](https://nx.dev/)
 - [NestJS](https://nestjs.com/), with [BullMQ](https://bullmq.io/), [PostgreSQL](https://www.postgresql.org/), [Redis](https://redis.io/)
-- [React](https://reactjs.org/), with [Recoil](https://recoiljs.org/), [Emotion](https://emotion.sh/) and [Lingui](https://lingui.dev/)
+- [React](https://reactjs.org/), with [Jotai](https://jotai.org/), [Linaria](https://linaria.dev/) and [Lingui](https://lingui.dev/)
 
 
 
@@ -120,6 +120,7 @@ Below are a few features we have implemented to date:
   <a href="https://greptile.com"><img src="./packages/twenty-website/public/images/readme/greptile.png" height="30" alt="Greptile" /></a>
   <a href="https://sentry.io/"><img src="./packages/twenty-website/public/images/readme/sentry.png" height="30" alt="Sentry" /></a>
   <a href="https://crowdin.com/"><img src="./packages/twenty-website/public/images/readme/crowdin.png" height="30" alt="Crowdin" /></a>
+  <a href="https://e2b.dev/"><img src="./packages/twenty-website/public/images/readme/e2b.svg" height="30" alt="E2B" /></a>
 </p>
 
   Thanks to these amazing services that we use and recommend for UI testing (Chromatic), code review (Greptile), catching bugs (Sentry) and translating (Crowdin).

eslint.config.mjs

@@ -83,6 +83,10 @@ export default [
               sourceTag: 'scope:frontend',
               onlyDependOnLibsWithTags: ['scope:shared', 'scope:frontend'],
             },
+            {
+              sourceTag: 'scope:zapier',
+              onlyDependOnLibsWithTags: ['scope:shared', 'scope:zapier'],
+            },
           ],
         },
       ],

nx.json

@@ -126,7 +126,7 @@
       "configurations": {
         "ci": {
           "ci": true,
-          "maxWorkers": 3
+          "maxWorkers": 1
         },
         "coverage": {
           "coverageReporters": ["lcov", "text"]
@@ -276,7 +276,7 @@
   "generators": {
     "@nx/react": {
       "application": {
-        "style": "@emotion/styled",
+        "style": "@linaria/react",
         "linter": "eslint",
         "bundler": "vite",
         "compiler": "swc",
@@ -284,7 +284,7 @@
         "projectNameAndRootFormat": "derived"
       },
       "library": {
-        "style": "@emotion/styled",
+        "style": "@linaria/react",
         "linter": "eslint",
         "bundler": "vite",
         "compiler": "swc",
@@ -292,7 +292,7 @@
         "projectNameAndRootFormat": "derived"
       },
       "component": {
-        "style": "@emotion/styled"
+        "style": "@linaria/react"
       }
     }
   },

package.json

@@ -2,14 +2,13 @@
   "private": true,
   "dependencies": {
     "@apollo/client": "^3.7.17",
-    "@emotion/react": "^11.11.1",
-    "@emotion/styled": "^11.11.0",
     "@floating-ui/react": "^0.24.3",
     "@linaria/core": "^6.2.0",
     "@linaria/react": "^6.2.1",
     "@radix-ui/colors": "^3.0.0",
     "@sniptt/guards": "^0.2.0",
     "@tabler/icons-react": "^3.31.0",
+    "@wyw-in-js/babel-preset": "^1.0.6",
     "@wyw-in-js/vite": "^0.7.0",
     "archiver": "^7.0.1",
     "danger-plugin-todos": "^1.3.1",
@@ -41,15 +40,15 @@
     "lodash.snakecase": "^4.1.1",
     "lodash.upperfirst": "^4.3.1",
     "microdiff": "^1.3.2",
+    "next-with-linaria": "^1.3.0",
     "planer": "^1.2.0",
     "pluralize": "^8.0.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "react-responsive": "^9.0.2",
-    "react-router-dom": "^6.4.4",
+    "react-router-dom": "^6.30.3",
     "react-tooltip": "^5.13.1",
-    "recoil": "^0.7.7",
-    "remark-gfm": "^3.0.1",
+    "remark-gfm": "^4.0.1",
     "rxjs": "^7.2.0",
     "semver": "^7.5.4",
     "slash": "^5.1.0",
@@ -73,28 +72,28 @@
     "@graphql-codegen/typescript": "^3.0.4",
     "@graphql-codegen/typescript-operations": "^3.0.4",
     "@graphql-codegen/typescript-react-apollo": "^3.3.7",
-    "@nx/eslint": "22.3.3",
-    "@nx/eslint-plugin": "22.3.3",
-    "@nx/jest": "22.3.3",
-    "@nx/js": "22.3.3",
-    "@nx/react": "22.3.3",
-    "@nx/storybook": "22.3.3",
-    "@nx/vite": "22.3.3",
-    "@nx/web": "22.3.3",
+    "@nx/eslint": "22.5.4",
+    "@nx/eslint-plugin": "22.5.4",
+    "@nx/jest": "22.5.4",
+    "@nx/js": "22.5.4",
+    "@nx/react": "22.5.4",
+    "@nx/storybook": "22.5.4",
+    "@nx/vite": "22.5.4",
+    "@nx/web": "22.5.4",
     "@sentry/types": "^8",
     "@storybook-community/storybook-addon-cookie": "^5.0.0",
     "@storybook/addon-coverage": "^3.0.0",
-    "@storybook/addon-docs": "^10.1.11",
-    "@storybook/addon-links": "^10.1.11",
-    "@storybook/addon-vitest": "^10.1.11",
+    "@storybook/addon-docs": "^10.2.13",
+    "@storybook/addon-links": "^10.2.13",
+    "@storybook/addon-vitest": "^10.2.13",
     "@storybook/icons": "^2.0.1",
-    "@storybook/react-vite": "^10.1.11",
+    "@storybook/react-vite": "^10.2.13",
     "@storybook/test-runner": "^0.24.2",
     "@stylistic/eslint-plugin": "^1.5.0",
-    "@swc-node/register": "1.11.1",
-    "@swc/cli": "^0.3.12",
-    "@swc/core": "1.15.11",
-    "@swc/helpers": "~0.5.18",
+    "@swc-node/register": "^1.11.1",
+    "@swc/cli": "^0.7.10",
+    "@swc/core": "^1.15.11",
+    "@swc/helpers": "~0.5.19",
     "@swc/jest": "^0.2.39",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/jest-dom": "^6.6.3",
@@ -160,7 +159,7 @@
     "eslint-plugin-react-hooks": "^5.0.0",
     "eslint-plugin-react-refresh": "^0.4.4",
     "eslint-plugin-simple-import-sort": "^10.0.0",
-    "eslint-plugin-storybook": "^10.1.11",
+    "eslint-plugin-storybook": "^10.2.13",
     "eslint-plugin-unicorn": "^56.0.1",
     "eslint-plugin-unused-imports": "^3.0.0",
     "http-server": "^14.1.1",
@@ -171,14 +170,14 @@
     "jsdom": "~22.1.0",
     "msw": "^2.12.7",
     "msw-storybook-addon": "^2.0.6",
-    "nx": "22.3.3",
+    "nx": "22.5.4",
     "prettier": "^3.1.1",
     "raw-loader": "^4.0.2",
     "rimraf": "^5.0.5",
     "source-map-support": "^0.5.20",
-    "storybook": "^10.1.11",
+    "storybook": "^10.2.13",
     "storybook-addon-mock-date": "2.0.0",
-    "storybook-addon-pseudo-states": "^10.1.11",
+    "storybook-addon-pseudo-states": "^10.2.13",
     "supertest": "^6.1.3",
     "ts-jest": "^29.1.1",
     "ts-loader": "^9.2.3",
@@ -202,10 +201,10 @@
     "type-fest": "4.10.1",
     "typescript": "5.9.2",
     "graphql-redis-subscriptions/ioredis": "^5.6.0",
-    "prosemirror-view": "1.40.0",
-    "prosemirror-transform": "1.10.4",
     "@lingui/core": "5.1.2",
-    "@types/qs": "6.9.16"
+    "@types/qs": "6.9.16",
+    "@wyw-in-js/transform@npm:0.6.0": "patch:@wyw-in-js/transform@npm%3A0.7.0#~/.yarn/patches/@wyw-in-js-transform-npm-0.7.0-ba641dc99f.patch",
+    "@wyw-in-js/transform@npm:0.7.0": "patch:@wyw-in-js/transform@npm%3A0.7.0#~/.yarn/patches/@wyw-in-js-transform-npm-0.7.0-ba641dc99f.patch"
   },
   "version": "0.2.1",
   "nx": {},

packages/create-twenty-app/README.md

@@ -31,10 +31,6 @@ See Twenty application documentation https://docs.twenty.com/developers/extend/c
 npx create-twenty-app@latest my-twenty-app
 cd my-twenty-app
 
-# If you don't use yarn@4
-corepack enable
-yarn install
-
 # Get help and list all available commands
 yarn twenty help
 
@@ -45,7 +41,7 @@ yarn twenty auth:login
 yarn twenty entity:add
 
 # Start dev mode: watches, builds, and syncs local changes to your workspace
-# (also auto-generates a typed API client in node_modules/twenty-sdk/generated)
+# (also auto-generates typed API clients — CoreApiClient and MetadataApiClient — in node_modules/twenty-sdk/generated)
 yarn twenty app:dev
 
 # Watch your application's function logs
@@ -54,6 +50,9 @@ yarn twenty function:logs
 # Execute a function with a JSON payload
 yarn twenty function:execute -n my-function -p '{"key": "value"}'
 
+# Execute the pre-install function
+yarn twenty function:execute --preInstall
+
 # Execute the post-install function
 yarn twenty function:execute --postInstall
 
@@ -90,12 +89,14 @@ In interactive mode, you can pick from:
 - **Example view** — a saved view for the example object (`views/example-view.ts`)
 - **Example navigation menu item** — a sidebar link (`navigation-menu-items/example-navigation-menu-item.ts`)
 - **Example skill** — an AI agent skill definition (`skills/example-skill.ts`)
+- **Integration test** — a vitest integration test verifying app installation (`__tests__/app-install.integration-test.ts`)
 
 ## What gets scaffolded
 
 **Core files (always created):**
 - `application-config.ts` — Application metadata configuration
 - `roles/default-role.ts` — Default role for logic functions
+- `logic-functions/pre-install.ts` — Pre-install logic function (runs before app installation)
 - `logic-functions/post-install.ts` — Post-install logic function (runs after app installation)
 - TypeScript configuration, ESLint, package.json, .gitignore
 - A prewired `twenty` script that delegates to the `twenty` CLI from twenty-sdk
@@ -108,13 +109,14 @@ In interactive mode, you can pick from:
 - `views/example-view.ts` — Example saved view for the example object
 - `navigation-menu-items/example-navigation-menu-item.ts` — Example sidebar navigation link
 - `skills/example-skill.ts` — Example AI agent skill definition
+- `__tests__/app-install.integration-test.ts` — Integration test that builds, installs, and verifies the app (includes `vitest.config.ts`, `tsconfig.spec.json`, and a setup file)
 
 ## Next steps
 - Run `yarn twenty help` to see all available commands.
 - Use `yarn twenty auth:login` to authenticate with your Twenty workspace.
 - Explore the generated project and add your first entity with `yarn twenty entity:add` (logic functions, front components, objects, roles, views, navigation menu items, skills).
 - Use `yarn twenty app:dev` while you iterate — it watches, builds, and syncs changes to your workspace in real time.
-- Types are auto‑generated by `yarn twenty app:dev` and stored in `node_modules/twenty-sdk/generated`.
+- Two typed API clients are auto‑generated by `yarn twenty app:dev` and stored in `node_modules/twenty-sdk/generated`: `CoreApiClient` (for workspace data via `/graphql`) and `MetadataApiClient` (for workspace configuration and file uploads via `/metadata`).
 
 
 ## Publish your application

packages/create-twenty-app/jest.config.mjs

@@ -1,5 +1,5 @@
 const jestConfig = {
-  displayName: 'twenty-cli',
+  displayName: 'create-twenty-app',
   preset: '../../jest.preset.js',
   testEnvironment: 'node',
   transformIgnorePatterns: ['../../node_modules/'],
@@ -15,6 +15,7 @@ const jestConfig = {
   },
   moduleNameMapper: {
     '^@/(.*)$': '<rootDir>/src/$1',
+    '^package.json$': '<rootDir>/package.json',
   },
   moduleFileExtensions: ['ts', 'js'],
   extensionsToTreatAsEsm: ['.ts'],

packages/create-twenty-app/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-twenty-app",
-  "version": "0.6.0",
+  "version": "0.6.3",
   "description": "Command-line interface to create Twenty application",
   "main": "dist/cli.cjs",
   "bin": "dist/cli.cjs",

packages/create-twenty-app/src/constants/base-application/LLMS.md

@@ -3,6 +3,9 @@
 - Documentation: https://docs.twenty.com/developers/extend/capabilities/apps
 - Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-sdk/src/cli/__tests__/apps/rich-app
 
+## UUID requirement
+- All generated UUIDs must be valid UUID v4.
+
 ## Common Pitfalls
 
 - Creating an object without an index view associated. Unless this is a technical object, user will need to visualize it.

packages/create-twenty-app/src/constants/base-application/README.md

@@ -36,6 +36,17 @@ yarn twenty function:execute  # Execute a function with JSON payload
 yarn twenty app:uninstall  # Uninstall app from workspace
 ```
 
+## Integration Tests
+
+If your project includes the example integration test (`src/__tests__/app-install.integration-test.ts`), you can run it with:
+
+```bash
+# Make sure a Twenty server is running at http://localhost:3000
+yarn test
+```
+
+The test builds and installs the app, then verifies it appears in the applications list. Test configuration (API URL and API key) is defined in `vitest.config.ts`.
+
 ## LLMs instructions
 
 Main docs and pitfalls are available in LLMS.md file.

packages/create-twenty-app/src/constants/base-application/tsconfig.json

@@ -27,5 +27,5 @@
       "~/*": ["./*"]
     }
   },
-  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts", "**/*.integration-test.ts"]
 }

packages/create-twenty-app/src/create-app.command.ts

@@ -115,6 +115,7 @@ export class CreateAppCommand {
         includeExampleView: false,
         includeExampleNavigationMenuItem: false,
         includeExampleSkill: false,
+        includeExampleIntegrationTest: false,
       };
     }
 
@@ -127,6 +128,7 @@ export class CreateAppCommand {
         includeExampleView: true,
         includeExampleNavigationMenuItem: true,
         includeExampleSkill: true,
+        includeExampleIntegrationTest: true,
       };
     }
 
@@ -171,12 +173,19 @@ export class CreateAppCommand {
             value: 'skill',
             checked: true,
           },
+          {
+            name: 'Integration test (vitest test verifying app installation)',
+            value: 'integrationTest',
+            checked: true,
+          },
         ],
       },
     ]);
 
     const includeField = selectedExamples.includes('field');
     const includeView = selectedExamples.includes('view');
+    const includeExampleIntegrationTest =
+      selectedExamples.includes('integrationTest');
     const includeObject =
       selectedExamples.includes('object') || includeField || includeView;
 
@@ -197,6 +206,7 @@ export class CreateAppCommand {
       includeExampleNavigationMenuItem:
         selectedExamples.includes('navigationMenuItem'),
       includeExampleSkill: selectedExamples.includes('skill'),
+      includeExampleIntegrationTest,
     };
   }
 
@@ -233,9 +243,9 @@ export class CreateAppCommand {
     console.log('');
     console.log(chalk.blue('Next steps:'));
     console.log(chalk.gray(`  cd ${dirName}`));
-    console.log(chalk.gray(`  corepack enable  # if you don't use yarn@4`));
-    console.log(chalk.gray(`  yarn install     # if you don't use yarn@4`));
-    console.log(chalk.gray('  yarn auth:login  # Authenticate with Twenty'));
-    console.log(chalk.gray('  yarn app:dev     # Start dev mode'));
+    console.log(
+      chalk.gray('  yarn twenty auth:login  # Authenticate with Twenty'),
+    );
+    console.log(chalk.gray('  yarn twenty app:dev     # Start dev mode'));
   }
 }

packages/create-twenty-app/src/types/scaffolding-options.ts

@@ -8,4 +8,5 @@ export type ExampleOptions = {
   includeExampleView: boolean;
   includeExampleNavigationMenuItem: boolean;
   includeExampleSkill: boolean;
+  includeExampleIntegrationTest: boolean;
 };

packages/create-twenty-app/src/utils/__tests__/app-template.spec.ts

@@ -1,11 +1,11 @@
 import { type ExampleOptions } from '@/types/scaffolding-options';
-import { GENERATED_DIR } from 'twenty-shared/application';
 import { copyBaseApplicationProject } from '@/utils/app-template';
 import * as fs from 'fs-extra';
 import { tmpdir } from 'os';
+import createTwentyAppPackageJson from 'package.json';
 import { join } from 'path';
+import { GENERATED_DIR } from 'twenty-shared/application';
 
-// Mock fs-extra's copy function to skip copying base template (not available during tests)
 jest.mock('fs-extra', () => {
   const actual = jest.requireActual('fs-extra');
   return {
@@ -25,6 +25,16 @@ const ALL_EXAMPLES: ExampleOptions = {
   includeExampleView: true,
   includeExampleNavigationMenuItem: true,
   includeExampleSkill: true,
+  includeExampleIntegrationTest: true,
+};
+
+const SEED_TSCONFIG = {
+  compilerOptions: { paths: { 'src/*': ['./src/*'] } },
+  exclude: ['node_modules', 'dist', '**/*.integration-test.ts'],
+};
+
+const seedTsconfig = async (directory: string) => {
+  await fs.writeJson(join(directory, 'tsconfig.json'), SEED_TSCONFIG);
 };
 
 const NO_EXAMPLES: ExampleOptions = {
@@ -35,23 +45,23 @@ const NO_EXAMPLES: ExampleOptions = {
   includeExampleFrontComponent: false,
   includeExampleView: false,
   includeExampleNavigationMenuItem: false,
+  includeExampleIntegrationTest: false,
 };
 
 describe('copyBaseApplicationProject', () => {
   let testAppDirectory: string;
 
   beforeEach(async () => {
-    // Create a unique temp directory for each test
     testAppDirectory = join(
       tmpdir(),
       `test-twenty-app-${Date.now()}-${Math.random().toString(36).slice(2)}`,
     );
     await fs.ensureDir(testAppDirectory);
+    await seedTsconfig(testAppDirectory);
     jest.clearAllMocks();
   });
 
   afterEach(async () => {
-    // Clean up temp directory after each test
     if (testAppDirectory && (await fs.pathExists(testAppDirectory))) {
       await fs.remove(testAppDirectory);
     }
@@ -66,15 +76,12 @@ describe('copyBaseApplicationProject', () => {
       exampleOptions: ALL_EXAMPLES,
     });
 
-    // Verify src/ folder exists
     const srcAppPath = join(testAppDirectory, 'src');
     expect(await fs.pathExists(srcAppPath)).toBe(true);
 
-    // Verify application-config.ts exists in src/
     const appConfigPath = join(srcAppPath, APPLICATION_FILE_NAME);
     expect(await fs.pathExists(appConfigPath)).toBe(true);
 
-    // Verify default-role.ts exists in src/
     const roleConfigPath = join(srcAppPath, 'roles', DEFAULT_ROLE_FILE_NAME);
     expect(await fs.pathExists(roleConfigPath)).toBe(true);
   });
@@ -94,7 +101,9 @@ describe('copyBaseApplicationProject', () => {
     const packageJson = await fs.readJson(packageJsonPath);
     expect(packageJson.name).toBe('my-test-app');
     expect(packageJson.version).toBe('0.1.0');
-    expect(packageJson.dependencies['twenty-sdk']).toBe('latest');
+    expect(packageJson.devDependencies['twenty-sdk']).toBe(
+      createTwentyAppPackageJson.version,
+    );
     expect(packageJson.scripts['twenty']).toBe('twenty');
   });
 
@@ -143,27 +152,29 @@ describe('copyBaseApplicationProject', () => {
     const appConfigPath = join(testAppDirectory, 'src', APPLICATION_FILE_NAME);
     const appConfigContent = await fs.readFile(appConfigPath, 'utf8');
 
-    // Verify it uses defineApplication
     expect(appConfigContent).toContain(
       "import { defineApplication } from 'twenty-sdk'",
     );
     expect(appConfigContent).toContain('export default defineApplication({');
 
-    // Verify it imports the role identifier
     expect(appConfigContent).toContain(
       "import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from 'src/roles/default-role'",
     );
 
-    // Verify display name and description
+    expect(appConfigContent).toContain(
+      'export const APPLICATION_UNIVERSAL_IDENTIFIER',
+    );
+    expect(appConfigContent).toContain(
+      'universalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER',
+    );
+
     expect(appConfigContent).toContain("displayName: 'My Test App'");
     expect(appConfigContent).toContain("description: 'A test application'");
 
-    // Verify it has a universalIdentifier (UUID format)
     expect(appConfigContent).toMatch(
-      /universalIdentifier: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'/,
+      /APPLICATION_UNIVERSAL_IDENTIFIER =\s*'[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'/,
     );
 
-    // Verify it references the role
     expect(appConfigContent).toContain(
       'defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER',
     );
@@ -186,29 +197,24 @@ describe('copyBaseApplicationProject', () => {
     );
     const roleConfigContent = await fs.readFile(roleConfigPath, 'utf8');
 
-    // Verify it uses defineRole
     expect(roleConfigContent).toContain(
       "import { defineRole } from 'twenty-sdk'",
     );
     expect(roleConfigContent).toContain('export default defineRole({');
 
-    // Verify it exports the universal identifier constant
     expect(roleConfigContent).toContain(
       'export const DEFAULT_ROLE_UNIVERSAL_IDENTIFIER',
     );
 
-    // Verify role label includes app name
     expect(roleConfigContent).toContain(
       "label: 'My Test App default function role'",
     );
 
-    // Verify default permissions
     expect(roleConfigContent).toContain('canReadAllObjectRecords: true');
     expect(roleConfigContent).toContain('canUpdateAllObjectRecords: true');
     expect(roleConfigContent).toContain('canSoftDeleteAllObjectRecords: true');
     expect(roleConfigContent).toContain('canDestroyAllObjectRecords: false');
 
-    // Verify it has a universalIdentifier (UUID format)
     expect(roleConfigContent).toMatch(
       /universalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER/,
     );
@@ -223,7 +229,6 @@ describe('copyBaseApplicationProject', () => {
       exampleOptions: ALL_EXAMPLES,
     });
 
-    // Verify fs.copy was called with correct destination
     expect(fs.copy).toHaveBeenCalledTimes(1);
     expect(fs.copy).toHaveBeenCalledWith(
       expect.stringContaining('base-application'),
@@ -247,9 +252,9 @@ describe('copyBaseApplicationProject', () => {
   });
 
   it('should generate unique UUIDs for each application', async () => {
-    // Create first app
     const firstAppDir = join(testAppDirectory, 'app1');
     await fs.ensureDir(firstAppDir);
+    await seedTsconfig(firstAppDir);
     await copyBaseApplicationProject({
       appName: 'app-one',
       appDisplayName: 'App One',
@@ -258,9 +263,9 @@ describe('copyBaseApplicationProject', () => {
       exampleOptions: ALL_EXAMPLES,
     });
 
-    // Create second app
     const secondAppDir = join(testAppDirectory, 'app2');
     await fs.ensureDir(secondAppDir);
+    await seedTsconfig(secondAppDir);
     await copyBaseApplicationProject({
       appName: 'app-two',
       appDisplayName: 'App Two',
@@ -269,7 +274,6 @@ describe('copyBaseApplicationProject', () => {
       exampleOptions: ALL_EXAMPLES,
     });
 
-    // Read both app configs
     const firstAppConfig = await fs.readFile(
       join(firstAppDir, 'src', APPLICATION_FILE_NAME),
       'utf8',
@@ -279,9 +283,8 @@ describe('copyBaseApplicationProject', () => {
       'utf8',
     );
 
-    // Extract UUIDs using regex
     const uuidRegex =
-      /universalIdentifier: '([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})'/;
+      /APPLICATION_UNIVERSAL_IDENTIFIER =\s*'([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})'/;
     const firstUuid = firstAppConfig.match(uuidRegex)?.[1];
     const secondUuid = secondAppConfig.match(uuidRegex)?.[1];
 
@@ -291,9 +294,9 @@ describe('copyBaseApplicationProject', () => {
   });
 
   it('should generate unique role UUIDs for each application', async () => {
-    // Create first app
     const firstAppDir = join(testAppDirectory, 'app1');
     await fs.ensureDir(firstAppDir);
+    await seedTsconfig(firstAppDir);
     await copyBaseApplicationProject({
       appName: 'app-one',
       appDisplayName: 'App One',
@@ -302,9 +305,9 @@ describe('copyBaseApplicationProject', () => {
       exampleOptions: ALL_EXAMPLES,
     });
 
-    // Create second app
     const secondAppDir = join(testAppDirectory, 'app2');
     await fs.ensureDir(secondAppDir);
+    await seedTsconfig(secondAppDir);
     await copyBaseApplicationProject({
       appName: 'app-two',
       appDisplayName: 'App Two',
@@ -323,7 +326,6 @@ describe('copyBaseApplicationProject', () => {
       'utf8',
     );
 
-    // Extract UUIDs using regex
     const uuidRegex =
       /DEFAULT_ROLE_UNIVERSAL_IDENTIFIER =\s*'([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})'/;
     const firstUuid = firstRoleConfig.match(uuidRegex)?.[1];
@@ -375,6 +377,24 @@ describe('copyBaseApplicationProject', () => {
             ),
           ),
         ).toBe(true);
+
+        expect(
+          await fs.pathExists(
+            join(srcPath, '__tests__', 'app-install.integration-test.ts'),
+          ),
+        ).toBe(true);
+
+        // Install functions should always exist
+        expect(
+          await fs.pathExists(
+            join(srcPath, 'logic-functions', 'pre-install.ts'),
+          ),
+        ).toBe(true);
+        expect(
+          await fs.pathExists(
+            join(srcPath, 'logic-functions', 'post-install.ts'),
+          ),
+        ).toBe(true);
       });
     });
 
@@ -390,7 +410,6 @@ describe('copyBaseApplicationProject', () => {
 
         const srcPath = join(testAppDirectory, 'src');
 
-        // Core files should exist
         expect(await fs.pathExists(join(srcPath, APPLICATION_FILE_NAME))).toBe(
           true,
         );
@@ -398,7 +417,18 @@ describe('copyBaseApplicationProject', () => {
           await fs.pathExists(join(srcPath, 'roles', DEFAULT_ROLE_FILE_NAME)),
         ).toBe(true);
 
-        // Example files should not exist
+        // Install functions should always exist (not gated by exampleOptions)
+        expect(
+          await fs.pathExists(
+            join(srcPath, 'logic-functions', 'pre-install.ts'),
+          ),
+        ).toBe(true);
+        expect(
+          await fs.pathExists(
+            join(srcPath, 'logic-functions', 'post-install.ts'),
+          ),
+        ).toBe(true);
+
         expect(
           await fs.pathExists(join(srcPath, 'objects', 'example-object.ts')),
         ).toBe(false);
@@ -427,6 +457,11 @@ describe('copyBaseApplicationProject', () => {
             ),
           ),
         ).toBe(false);
+        expect(
+          await fs.pathExists(
+            join(srcPath, '__tests__', 'app-install.integration-test.ts'),
+          ),
+        ).toBe(false);
       });
     });
 
@@ -445,6 +480,7 @@ describe('copyBaseApplicationProject', () => {
             includeExampleFrontComponent: true,
             includeExampleView: false,
             includeExampleNavigationMenuItem: false,
+            includeExampleIntegrationTest: false,
           },
         });
 
@@ -482,6 +518,7 @@ describe('copyBaseApplicationProject', () => {
             includeExampleFrontComponent: false,
             includeExampleView: false,
             includeExampleNavigationMenuItem: false,
+            includeExampleIntegrationTest: false,
           },
         });
 
@@ -539,6 +576,7 @@ describe('copyBaseApplicationProject', () => {
     it('should generate unique UUIDs for example objects across apps', async () => {
       const firstAppDir = join(testAppDirectory, 'app1');
       await fs.ensureDir(firstAppDir);
+      await seedTsconfig(firstAppDir);
       await copyBaseApplicationProject({
         appName: 'app-one',
         appDisplayName: 'App One',
@@ -549,6 +587,7 @@ describe('copyBaseApplicationProject', () => {
 
       const secondAppDir = join(testAppDirectory, 'app2');
       await fs.ensureDir(secondAppDir);
+      await seedTsconfig(secondAppDir);
       await copyBaseApplicationProject({
         appName: 'app-two',
         appDisplayName: 'App Two',
@@ -676,4 +715,162 @@ describe('copyBaseApplicationProject', () => {
       expect(content).toContain('position: 0');
     });
   });
+
+  describe('pre-install logic function', () => {
+    it('should create pre-install.ts with definePreInstallLogicFunction and typed payload', async () => {
+      await copyBaseApplicationProject({
+        appName: 'my-test-app',
+        appDisplayName: 'My Test App',
+        appDescription: 'A test application',
+        appDirectory: testAppDirectory,
+        exampleOptions: NO_EXAMPLES,
+      });
+
+      const preInstallPath = join(
+        testAppDirectory,
+        'src',
+        'logic-functions',
+        'pre-install.ts',
+      );
+
+      expect(await fs.pathExists(preInstallPath)).toBe(true);
+
+      const content = await fs.readFile(preInstallPath, 'utf8');
+
+      expect(content).toContain(
+        "import { definePreInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk'",
+      );
+      expect(content).toContain(
+        'export default definePreInstallLogicFunction({',
+      );
+      expect(content).toContain("name: 'pre-install'");
+      expect(content).toContain('timeoutSeconds: 300');
+      expect(content).toContain(
+        'const handler = async (payload: InstallLogicFunctionPayload): Promise<void>',
+      );
+      expect(content).toContain('payload.previousVersion');
+
+      // Verify it has a universalIdentifier (UUID format)
+      expect(content).toMatch(
+        /universalIdentifier: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'/,
+      );
+    });
+
+    it('should always create pre-install.ts regardless of example options', async () => {
+      await copyBaseApplicationProject({
+        appName: 'my-test-app',
+        appDisplayName: 'My Test App',
+        appDescription: 'A test application',
+        appDirectory: testAppDirectory,
+        exampleOptions: NO_EXAMPLES,
+      });
+
+      const preInstallPath = join(
+        testAppDirectory,
+        'src',
+        'logic-functions',
+        'pre-install.ts',
+      );
+
+      expect(await fs.pathExists(preInstallPath)).toBe(true);
+    });
+  });
+
+  describe('integration test', () => {
+    it('should include vitest and test scripts in package.json when enabled', async () => {
+      await copyBaseApplicationProject({
+        appName: 'my-test-app',
+        appDisplayName: 'My Test App',
+        appDescription: 'A test application',
+        appDirectory: testAppDirectory,
+        exampleOptions: ALL_EXAMPLES,
+      });
+
+      const packageJson = await fs.readJson(
+        join(testAppDirectory, 'package.json'),
+      );
+
+      expect(packageJson.scripts.test).toBe('vitest run');
+      expect(packageJson.scripts['test:watch']).toBe('vitest');
+      expect(packageJson.devDependencies.vitest).toBeDefined();
+    });
+
+    it('should not include vitest or test scripts when disabled', async () => {
+      await copyBaseApplicationProject({
+        appName: 'my-test-app',
+        appDisplayName: 'My Test App',
+        appDescription: 'A test application',
+        appDirectory: testAppDirectory,
+        exampleOptions: NO_EXAMPLES,
+      });
+
+      const packageJson = await fs.readJson(
+        join(testAppDirectory, 'package.json'),
+      );
+
+      expect(packageJson.scripts.test).toBeUndefined();
+      expect(packageJson.scripts['test:watch']).toBeUndefined();
+      expect(packageJson.devDependencies.vitest).toBeUndefined();
+    });
+  });
+
+  describe('post-install logic function', () => {
+    it('should create post-install.ts with definePostInstallLogicFunction and typed payload', async () => {
+      await copyBaseApplicationProject({
+        appName: 'my-test-app',
+        appDisplayName: 'My Test App',
+        appDescription: 'A test application',
+        appDirectory: testAppDirectory,
+        exampleOptions: NO_EXAMPLES,
+      });
+
+      const postInstallPath = join(
+        testAppDirectory,
+        'src',
+        'logic-functions',
+        'post-install.ts',
+      );
+
+      expect(await fs.pathExists(postInstallPath)).toBe(true);
+
+      const content = await fs.readFile(postInstallPath, 'utf8');
+
+      expect(content).toContain(
+        "import { definePostInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk'",
+      );
+      expect(content).toContain(
+        'export default definePostInstallLogicFunction({',
+      );
+      expect(content).toContain("name: 'post-install'");
+      expect(content).toContain('timeoutSeconds: 300');
+      expect(content).toContain(
+        'const handler = async (payload: InstallLogicFunctionPayload): Promise<void>',
+      );
+      expect(content).toContain('payload.previousVersion');
+
+      // Verify it has a universalIdentifier (UUID format)
+      expect(content).toMatch(
+        /universalIdentifier: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'/,
+      );
+    });
+
+    it('should always create post-install.ts regardless of example options', async () => {
+      await copyBaseApplicationProject({
+        appName: 'my-test-app',
+        appDisplayName: 'My Test App',
+        appDescription: 'A test application',
+        appDirectory: testAppDirectory,
+        exampleOptions: NO_EXAMPLES,
+      });
+
+      const postInstallPath = join(
+        testAppDirectory,
+        'src',
+        'logic-functions',
+        'post-install.ts',
+      );
+
+      expect(await fs.pathExists(postInstallPath)).toBe(true);
+    });
+  });
 });

packages/create-twenty-app/src/utils/__tests__/test-template.spec.ts

@@ -0,0 +1,144 @@
+import { scaffoldIntegrationTest } from '@/utils/test-template';
+import * as fs from 'fs-extra';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+describe('scaffoldIntegrationTest', () => {
+  let testAppDirectory: string;
+  let sourceFolderPath: string;
+
+  beforeEach(async () => {
+    testAppDirectory = join(
+      tmpdir(),
+      `test-twenty-app-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+    sourceFolderPath = join(testAppDirectory, 'src');
+    await fs.ensureDir(sourceFolderPath);
+
+    await fs.writeJson(join(testAppDirectory, 'tsconfig.json'), {
+      compilerOptions: {
+        paths: { 'src/*': ['./src/*'] },
+      },
+      exclude: ['node_modules', 'dist', '**/*.integration-test.ts'],
+    });
+  });
+
+  afterEach(async () => {
+    if (testAppDirectory && (await fs.pathExists(testAppDirectory))) {
+      await fs.remove(testAppDirectory);
+    }
+  });
+
+  describe('integration test file', () => {
+    it('should create app-install.integration-test.ts with correct structure', async () => {
+      await scaffoldIntegrationTest({
+        appDirectory: testAppDirectory,
+        sourceFolderPath,
+      });
+
+      const testPath = join(
+        sourceFolderPath,
+        '__tests__',
+        'app-install.integration-test.ts',
+      );
+
+      expect(await fs.pathExists(testPath)).toBe(true);
+
+      const content = await fs.readFile(testPath, 'utf8');
+
+      expect(content).toContain(
+        "import { appBuild, appUninstall } from 'twenty-sdk/cli'",
+      );
+      expect(content).toContain(
+        "import { MetadataApiClient } from 'twenty-sdk/generated'",
+      );
+      expect(content).toContain(
+        "import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application-config'",
+      );
+      expect(content).toContain('TWENTY_TEST_API_KEY');
+      expect(content).toContain('assertServerIsReachable');
+      expect(content).toContain('appBuild');
+      expect(content).toContain('appUninstall');
+      expect(content).toContain('findManyApplications');
+      expect(content).toContain('APPLICATION_UNIVERSAL_IDENTIFIER');
+    });
+  });
+
+  describe('setup-test file', () => {
+    it('should create setup-test.ts with SDK config bootstrap', async () => {
+      await scaffoldIntegrationTest({
+        appDirectory: testAppDirectory,
+        sourceFolderPath,
+      });
+
+      const setupTestPath = join(
+        sourceFolderPath,
+        '__tests__',
+        'setup-test.ts',
+      );
+
+      expect(await fs.pathExists(setupTestPath)).toBe(true);
+
+      const content = await fs.readFile(setupTestPath, 'utf8');
+
+      expect(content).toContain('.twenty-sdk-test');
+      expect(content).toContain('config.json');
+      expect(content).toContain('process.env.TWENTY_API_URL');
+      expect(content).toContain('process.env.TWENTY_TEST_API_KEY');
+    });
+  });
+
+  describe('vitest config', () => {
+    it('should create vitest.config.ts with env vars and setup file', async () => {
+      await scaffoldIntegrationTest({
+        appDirectory: testAppDirectory,
+        sourceFolderPath,
+      });
+
+      const vitestConfigPath = join(testAppDirectory, 'vitest.config.ts');
+
+      expect(await fs.pathExists(vitestConfigPath)).toBe(true);
+
+      const content = await fs.readFile(vitestConfigPath, 'utf8');
+
+      expect(content).toContain('TWENTY_TEST_API_KEY');
+      expect(content).toContain('TWENTY_API_URL');
+      expect(content).toContain('setup-test.ts');
+      expect(content).toContain('tsconfig.spec.json');
+      expect(content).toContain('integration-test.ts');
+    });
+  });
+
+  describe('tsconfig.spec.json', () => {
+    it('should create tsconfig.spec.json extending the base tsconfig', async () => {
+      await scaffoldIntegrationTest({
+        appDirectory: testAppDirectory,
+        sourceFolderPath,
+      });
+
+      const tsconfigSpecPath = join(testAppDirectory, 'tsconfig.spec.json');
+
+      expect(await fs.pathExists(tsconfigSpecPath)).toBe(true);
+
+      const tsconfigSpec = await fs.readJson(tsconfigSpecPath);
+
+      expect(tsconfigSpec.extends).toBe('./tsconfig.json');
+      expect(tsconfigSpec.compilerOptions.composite).toBe(true);
+      expect(tsconfigSpec.include).toContain('src/**/*.ts');
+      expect(tsconfigSpec.exclude).not.toContain('**/*.integration-test.ts');
+    });
+
+    it('should add a reference to tsconfig.spec.json in tsconfig.json', async () => {
+      await scaffoldIntegrationTest({
+        appDirectory: testAppDirectory,
+        sourceFolderPath,
+      });
+
+      const tsconfig = await fs.readJson(
+        join(testAppDirectory, 'tsconfig.json'),
+      );
+
+      expect(tsconfig.references).toEqual([{ path: './tsconfig.spec.json' }]);
+    });
+  });
+});

packages/create-twenty-app/src/utils/app-template.ts

@@ -1,9 +1,11 @@
 import * as fs from 'fs-extra';
 import { join } from 'path';
-import { v4 } from 'uuid';
 import { ASSETS_DIR } from 'twenty-shared/application';
+import { v4 } from 'uuid';
 
 import { type ExampleOptions } from '@/types/scaffolding-options';
+import { scaffoldIntegrationTest } from '@/utils/test-template';
+import createTwentyAppPackageJson from 'package.json';
 
 const SRC_FOLDER = 'src';
 
@@ -22,7 +24,11 @@ export const copyBaseApplicationProject = async ({
 }) => {
   await fs.copy(join(__dirname, './constants/base-application'), appDirectory);
 
-  await createPackageJson({ appName, appDirectory });
+  await createPackageJson({
+    appName,
+    appDirectory,
+    includeExampleIntegrationTest: exampleOptions.includeExampleIntegrationTest,
+  });
 
   await createGitignore(appDirectory);
 
@@ -97,6 +103,19 @@ export const copyBaseApplicationProject = async ({
     });
   }
 
+  if (exampleOptions.includeExampleIntegrationTest) {
+    await scaffoldIntegrationTest({
+      appDirectory,
+      sourceFolderPath,
+    });
+  }
+
+  await createDefaultPreInstallFunction({
+    appDirectory: sourceFolderPath,
+    fileFolder: 'logic-functions',
+    fileName: 'pre-install.ts',
+  });
+
   await createDefaultPostInstallFunction({
     appDirectory: sourceFolderPath,
     fileFolder: 'logic-functions',
@@ -140,8 +159,7 @@ generated
 # dev
 /dist/
 
-.twenty/*
-!.twenty/output/
+.twenty
 
 # production
 /build
@@ -161,6 +179,7 @@ yarn-error.log*
 
 # typescript
 *.tsbuildinfo
+*.d.ts
 `;
 
   await fs.writeFile(join(appDirectory, '.gitignore'), gitignoreContent);
@@ -268,6 +287,36 @@ export default defineLogicFunction({
   await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
 };
 
+const createDefaultPreInstallFunction = async ({
+  appDirectory,
+  fileFolder,
+  fileName,
+}: {
+  appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
+}) => {
+  const universalIdentifier = v4();
+
+  const content = `import { definePreInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk';
+
+const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
+  console.log('Pre install logic function executed successfully!', payload.previousVersion);
+};
+
+export default definePreInstallLogicFunction({
+  universalIdentifier: '${universalIdentifier}',
+  name: 'pre-install',
+  description: 'Runs before installation to prepare the application.',
+  timeoutSeconds: 300,
+  handler,
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};
+
 const createDefaultPostInstallFunction = async ({
   appDirectory,
   fileFolder,
@@ -279,16 +328,14 @@ const createDefaultPostInstallFunction = async ({
 }) => {
   const universalIdentifier = v4();
 
-  const content = `import { defineLogicFunction } from 'twenty-sdk';
+  const content = `import { definePostInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk';
 
-export const POST_INSTALL_UNIVERSAL_IDENTIFIER = '${universalIdentifier}';
-
-const handler = async (): Promise<void> => {
-  console.log('Post install logic function executed successfully!');
+const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
+  console.log('Post install logic function executed successfully!', payload.previousVersion);
 };
 
-export default defineLogicFunction({
-  universalIdentifier: POST_INSTALL_UNIVERSAL_IDENTIFIER,
+export default definePostInstallLogicFunction({
+  universalIdentifier: '${universalIdentifier}',
   name: 'post-install',
   description: 'Runs after installation to set up the application.',
   timeoutSeconds: 300,
@@ -475,16 +522,19 @@ const createApplicationConfig = async ({
   fileFolder?: string;
   fileName: string;
 }) => {
+  const universalIdentifier = v4();
+
   const content = `import { defineApplication } from 'twenty-sdk';
 import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from 'src/roles/default-role';
-import { POST_INSTALL_UNIVERSAL_IDENTIFIER } from 'src/logic-functions/post-install';
+
+export const APPLICATION_UNIVERSAL_IDENTIFIER =
+  '${universalIdentifier}';
 
 export default defineApplication({
-  universalIdentifier: '${v4()}',
+  universalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
   displayName: '${displayName}',
   description: '${description ?? ''}',
   defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
-  postInstallLogicFunctionUniversalIdentifier: POST_INSTALL_UNIVERSAL_IDENTIFIER,
 });
 `;
 
@@ -495,10 +545,35 @@ export default defineApplication({
 const createPackageJson = async ({
   appName,
   appDirectory,
+  includeExampleIntegrationTest,
 }: {
   appName: string;
   appDirectory: string;
+  includeExampleIntegrationTest: boolean;
 }) => {
+  const scripts: Record<string, string> = {
+    twenty: 'twenty',
+    lint: 'eslint',
+    'lint:fix': 'eslint --fix',
+  };
+
+  const devDependencies: Record<string, string> = {
+    typescript: '^5.9.3',
+    '@types/node': '^24.7.2',
+    '@types/react': '^18.2.0',
+    react: '^18.2.0',
+    eslint: '^9.32.0',
+    'typescript-eslint': '^8.50.0',
+    'twenty-sdk': createTwentyAppPackageJson.version,
+  };
+
+  if (includeExampleIntegrationTest) {
+    scripts.test = 'vitest run';
+    scripts['test:watch'] = 'vitest';
+    devDependencies.vitest = '^3.1.1';
+    devDependencies['vite-tsconfig-paths'] = '^4.2.1';
+  }
+
   const packageJson = {
     name: appName,
     version: '0.1.0',
@@ -509,22 +584,8 @@ const createPackageJson = async ({
       yarn: '>=4.0.2',
     },
     packageManager: '[email protected]',
-    scripts: {
-      twenty: 'twenty',
-      lint: 'eslint',
-      'lint:fix': 'eslint --fix',
-    },
-    dependencies: {
-      'twenty-sdk': 'latest',
-    },
-    devDependencies: {
-      typescript: '^5.9.3',
-      '@types/node': '^24.7.2',
-      '@types/react': '^18.2.0',
-      react: '^18.2.0',
-      eslint: '^9.32.0',
-      'typescript-eslint': '^8.50.0',
-    },
+    scripts,
+    devDependencies,
   };
 
   await fs.writeFile(

packages/create-twenty-app/src/utils/install.ts

@@ -6,7 +6,13 @@ const execPromise = promisify(exec);
 
 export const install = async (root: string) => {
   try {
-    await execPromise('yarn', { cwd: root });
+    await execPromise('corepack enable', { cwd: root });
+  } catch (error: any) {
+    console.warn(chalk.yellow('corepack enabled failed:'), error.stderr);
+  }
+
+  try {
+    await execPromise('yarn install', { cwd: root });
   } catch (error: any) {
     console.error(chalk.red('yarn install failed:'), error.stdout);
   }

packages/create-twenty-app/src/utils/test-template.ts

@@ -0,0 +1,226 @@
+import * as fs from 'fs-extra';
+import { join } from 'path';
+
+const SEED_API_KEY =
+  'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ1c2VySWQiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ3b3Jrc3BhY2VJZCI6IjIwMjAyMDIwLTFjMjUtNGQwMi1iZjI1LTZhZWNjZjdlYTQxOSIsIndvcmtzcGFjZU1lbWJlcklkIjoiMjAyMDIwMjAtNDYzZi00MzViLTgyOGMtMTA3ZTAwN2EyNzExIiwidXNlcldvcmtzcGFjZUlkIjoiMjAyMDIwMjAtMWU3Yy00M2Q5LWE1ZGItNjg1YjUwNjlkODE2IiwidHlwZSI6IkFDQ0VTUyIsImF1dGhQcm92aWRlciI6InBhc3N3b3JkIiwiaWF0IjoxNzUxMjgxNzA0LCJleHAiOjIwNjY4NTc3MDR9.HMGqCsVlOAPVUBhKSGlD1X86VoHKt4LIUtET3CGIdik';
+
+export const scaffoldIntegrationTest = async ({
+  appDirectory,
+  sourceFolderPath,
+}: {
+  appDirectory: string;
+  sourceFolderPath: string;
+}) => {
+  await createIntegrationTest({
+    appDirectory: sourceFolderPath,
+    fileFolder: '__tests__',
+    fileName: 'app-install.integration-test.ts',
+  });
+
+  await createSetupTest({
+    appDirectory: sourceFolderPath,
+    fileFolder: '__tests__',
+    fileName: 'setup-test.ts',
+  });
+
+  await createVitestConfig(appDirectory);
+  await createTsconfigSpec(appDirectory);
+};
+
+const createVitestConfig = async (appDirectory: string) => {
+  const content = `import tsconfigPaths from 'vite-tsconfig-paths';
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  plugins: [
+    tsconfigPaths({
+      projects: ['tsconfig.spec.json'],
+      ignoreConfigErrors: true,
+    }),
+  ],
+  test: {
+    testTimeout: 120_000,
+    hookTimeout: 120_000,
+    include: ['src/**/*.integration-test.ts'],
+    setupFiles: ['src/__tests__/setup-test.ts'],
+    env: {
+      TWENTY_API_URL: 'http://localhost:3000',
+      TWENTY_TEST_API_KEY:
+        '${SEED_API_KEY}',
+    },
+  },
+});
+`;
+
+  await fs.writeFile(join(appDirectory, 'vitest.config.ts'), content);
+};
+
+const createTsconfigSpec = async (appDirectory: string) => {
+  const tsconfigSpec = {
+    extends: './tsconfig.json',
+    compilerOptions: {
+      composite: true,
+      types: ['vitest/globals'],
+    },
+    include: ['src/**/*.ts', 'src/**/*.tsx'],
+    exclude: ['node_modules', 'dist'],
+  };
+
+  await fs.writeFile(
+    join(appDirectory, 'tsconfig.spec.json'),
+    JSON.stringify(tsconfigSpec, null, 2),
+  );
+
+  const tsconfigPath = join(appDirectory, 'tsconfig.json');
+  const tsconfig = await fs.readJson(tsconfigPath);
+
+  tsconfig.references = [{ path: './tsconfig.spec.json' }];
+
+  await fs.writeFile(tsconfigPath, JSON.stringify(tsconfig, null, 2));
+};
+
+const createSetupTest = async ({
+  appDirectory,
+  fileFolder,
+  fileName,
+}: {
+  appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
+}) => {
+  const content = `import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { beforeAll } from 'vitest';
+
+const TEST_CONFIG_DIR = path.join(os.tmpdir(), '.twenty-sdk-test');
+
+beforeAll(() => {
+  fs.mkdirSync(TEST_CONFIG_DIR, { recursive: true });
+
+  const configFile = {
+    profiles: {
+      default: {
+        apiUrl: process.env.TWENTY_API_URL,
+        apiKey: process.env.TWENTY_TEST_API_KEY,
+      },
+    },
+  };
+
+  fs.writeFileSync(
+    path.join(TEST_CONFIG_DIR, 'config.json'),
+    JSON.stringify(configFile, null, 2),
+  );
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};
+
+const createIntegrationTest = async ({
+  appDirectory,
+  fileFolder,
+  fileName,
+}: {
+  appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
+}) => {
+  const content = `import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application-config';
+import { appBuild, appUninstall } from 'twenty-sdk/cli';
+import { MetadataApiClient } from 'twenty-sdk/generated';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+const APP_PATH = process.cwd();
+const TWENTY_API_URL = process.env.TWENTY_API_URL ?? 'http://localhost:3000';
+
+const assertServerIsReachable = async () => {
+  let response: Response;
+
+  try {
+    response = await fetch(\`\${TWENTY_API_URL}/healthz\`);
+  } catch {
+    throw new Error(
+      \`Twenty server is not reachable at \${TWENTY_API_URL}. \` +
+        'Make sure the server is running before executing integration tests.',
+    );
+  }
+
+  if (!response.ok) {
+    throw new Error(\`Server at \${TWENTY_API_URL} returned \${response.status}\`);
+  }
+};
+
+describe('App installation', () => {
+  let appInstalled = false;
+
+  beforeAll(async () => {
+    await assertServerIsReachable();
+
+    const buildResult = await appBuild({
+      appPath: APP_PATH,
+      onProgress: (message: string) => console.log(\`[build] \${message}\`),
+    });
+
+    if (!buildResult.success) {
+      throw new Error(
+        \`App build failed: \${buildResult.error?.message ?? 'Unknown error'}\`,
+      );
+    }
+
+    appInstalled = true;
+  });
+
+  afterAll(async () => {
+    if (!appInstalled) {
+      return;
+    }
+
+    const uninstallResult = await appUninstall({ appPath: APP_PATH });
+
+    if (!uninstallResult.success) {
+      console.warn(
+        \`App uninstall failed: \${uninstallResult.error?.message ?? 'Unknown error'}\`,
+      );
+    }
+  });
+
+  it('should find the installed app in the applications list', async () => {
+    const apiKey = process.env.TWENTY_TEST_API_KEY;
+
+    if (!apiKey) {
+      throw new Error(
+        'No API key found. Set TWENTY_TEST_API_KEY in your vitest config env.',
+      );
+    }
+
+    const metadataClient = new MetadataApiClient({
+      url: \`\${TWENTY_API_URL}/metadata\`,
+      headers: {
+        Authorization: \`Bearer \${apiKey}\`,
+      },
+    });
+
+    const result = await metadataClient.query({
+      findManyApplications: {
+        id: true,
+        name: true,
+        universalIdentifier: true,
+      },
+    });
+
+    const installedApp = result.findManyApplications.find(
+      (application: { universalIdentifier: string }) =>
+        application.universalIdentifier ===
+        APPLICATION_UNIVERSAL_IDENTIFIER,
+    );
+
+    expect(installedApp).toBeDefined();
+  });
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};

packages/create-twenty-app/tsconfig.json

@@ -11,7 +11,8 @@
     "noEmit": true,
     "types": ["jest", "node"],
     "paths": {
-      "@/*": ["./src/*"]
+      "@/*": ["./src/*"],
+      "package.json": ["./package.json"]
     },
     "jsx": "react"
   },
@@ -22,5 +23,8 @@
     "**/__mocks__/**/*",
     "vite.config.ts",
     "jest.config.mjs"
+  ],
+  "exclude": [
+    "src/constants/base-application/vitest.config.ts"
   ]
 }

packages/twenty-apps/community/apollo-enrich/.gitignore

@@ -0,0 +1,38 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn
+
+# codegen
+generated
+
+# testing
+/coverage
+
+# dev
+/dist/
+
+.twenty/*
+!.twenty/output/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# typescript
+*.tsbuildinfo

packages/twenty-apps/community/apollo-enrich/.nvmrc

@@ -0,0 +1 @@
+24.5.0

packages/twenty-apps/community/apollo-enrich/.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

packages/twenty-apps/community/apollo-enrich/LLMS.md

@@ -0,0 +1,12 @@
+## Base documentation
+
+- Documentation: https://docs.twenty.com/developers/extend/capabilities/apps
+- Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-sdk/src/cli/__tests__/apps/rich-app
+
+## UUID requirement
+- All generated UUIDs must be valid UUID v4.
+
+## Common Pitfalls
+
+- Creating an object without an index view associated. Unless this is a technical object, user will need to visualize it.
+- Creating a view without a navigationMenuItem associated. This will make the view available on the left sidebar.

packages/twenty-apps/community/apollo-enrich/README.md

@@ -0,0 +1,51 @@
+This is a [Twenty](https://twenty.com) application project bootstrapped with [`create-twenty-app`](https://www.npmjs.com/package/create-twenty-app).
+
+## Getting Started
+
+First, authenticate to your workspace:
+
+```bash
+yarn twenty auth:login
+```
+
+Then, start development mode to sync your app and watch for changes:
+
+```bash
+yarn twenty app:dev
+```
+
+Open your Twenty instance and go to `/settings/applications` section to see the result.
+
+## Available Commands
+
+Run `yarn twenty help` to list all available commands. Common commands:
+
+```bash
+# Authentication
+yarn twenty auth:login     # Authenticate with Twenty
+yarn twenty auth:logout    # Remove credentials
+yarn twenty auth:status    # Check auth status
+yarn twenty auth:switch    # Switch default workspace
+yarn twenty auth:list      # List all configured workspaces
+
+# Application
+yarn twenty app:dev        # Start dev mode (watch, build, sync, and auto-generate typed client)
+yarn twenty entity:add     # Add a new entity (object, field, function, front-component, role, view, navigation-menu-item)
+yarn twenty function:logs  # Stream function logs
+yarn twenty function:execute  # Execute a function with JSON payload
+yarn twenty app:uninstall  # Uninstall app from workspace
+```
+
+## LLMs instructions
+
+Main docs and pitfalls are available in LLMS.md file.
+
+## Learn More
+
+To learn more about Twenty applications, take a look at the following resources:
+
+- [twenty-sdk](https://www.npmjs.com/package/twenty-sdk) - learn about `twenty-sdk` tool.
+- [Twenty doc](https://docs.twenty.com/) - Twenty's documentation.
+- Join our [Discord](https://discord.gg/cx5n4Jzs57)
+
+You can check out [the Twenty GitHub repository](https://github.com/twentyhq/twenty) - your feedback and contributions are welcome!

packages/twenty-apps/community/apollo-enrich/eslint.config.mjs

@@ -0,0 +1,29 @@
+import js from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default [
+  // Base JS recommended rules
+  js.configs.recommended,
+
+  // TypeScript recommended rules
+  ...tseslint.configs.recommended,
+
+  {
+    files: ['**/*.ts', '**/*.tsx'],
+    languageOptions: {
+      parserOptions: {
+        project: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      // Common TypeScript-friendly tweaks
+      '@typescript-eslint/no-unused-vars': [
+        'warn',
+        { argsIgnorePattern: '^_' },
+      ],
+      '@typescript-eslint/no-explicit-any': 'off',
+      'no-unused-vars': 'off', // handled by TS rule
+    },
+  },
+];

packages/twenty-apps/community/apollo-enrich/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "apollo-enrich",
+  "version": "0.1.0",
+  "license": "MIT",
+  "engines": {
+    "node": "^24.5.0",
+    "npm": "please-use-yarn",
+    "yarn": ">=4.0.2"
+  },
+  "packageManager": "[email protected]",
+  "scripts": {
+    "twenty": "twenty",
+    "lint": "eslint",
+    "lint:fix": "eslint --fix"
+  },
+  "dependencies": {
+    "twenty-sdk": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^24.7.2",
+    "@types/react": "^18.2.0",
+    "eslint": "^9.32.0",
+    "react": "^18.2.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.50.0"
+  }
+}

packages/twenty-apps/community/apollo-enrich/src/application-config.ts

@@ -0,0 +1,54 @@
+import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from 'src/roles/default-role';
+import { defineApplication } from 'twenty-sdk';
+
+export default defineApplication({
+  universalIdentifier: 'ac1d2ed1-8835-4bd4-9043-28b46fdda465',
+  displayName: 'Apollo enrichment',
+  description: 'Data enrichment with Apollo to keep your data accurate',
+  defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+  settingsCustomTabFrontComponentUniversalIdentifier: '50d59f7c-eada-4731-aacd-8e45371e1040',
+  applicationVariables: {
+    APOLLO_CLIENT_ID: {
+      universalIdentifier: '5852219e-7757-463e-9e7c-80980203794c',
+      isSecret: true,
+      value: '',
+      description: 'Apollo Client ID',
+    },
+    APOLLO_CLIENT_SECRET: {
+      universalIdentifier: 'a032349d-9458-4381-8505-82547276434a',
+      isSecret: true,
+      value: '',
+      description: 'Apollo Client Secret',
+    },
+    APOLLO_OAUTH_URL: {
+      universalIdentifier: '1d42411c-5809-4093-873a-8121b1302475',
+      isSecret: false,
+      value: '',
+      description: 'Apollo OAuth URL',
+    },
+    APOLLO_REDIRECT_URI: {
+      universalIdentifier: 'c8d9e0f1-2a3b-4c5d-6e7f-8a9b0c1d2e3f',
+      isSecret: false,
+      value: '',
+      description: 'Apollo OAuth redirect URI',
+    },
+    APOLLO_REGISTERED_URL: {
+      universalIdentifier: '672a6fce-5565-43bc-9a3b-7f2c33620770',
+      isSecret: false,
+      value: '',
+      description: 'Apollo registered URL',
+    },
+    APOLLO_ACCESS_TOKEN: {
+      universalIdentifier: '672a6fce-5565-43bc-9a3b-7f2c33620771',
+      isSecret: true,
+      value: '',
+      description: 'Apollo access token',
+    },
+    APOLLO_REFRESH_TOKEN: {
+      universalIdentifier: '672a6fce-5565-43bc-9a3b-7f2c33620772',
+      isSecret: true,
+      value: '',
+      description: 'Apollo refresh token',
+    },
+  },
+});

packages/twenty-apps/community/apollo-enrich/src/fields/apollo-founded-year.field.ts

@@ -0,0 +1,16 @@
+import {
+  defineField,
+  FieldType,
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
+} from 'twenty-sdk';
+
+export default defineField({
+  universalIdentifier: 'da15cfc6-3657-457d-8757-4ba11b5bb6e1',
+  objectUniversalIdentifier:
+    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
+  type: FieldType.NUMBER,
+  name: 'apolloFoundedYear',
+  label: 'Founded Year',
+  description: 'Year the company was founded, from Apollo enrichment',
+  icon: 'IconCalendar',
+});

packages/twenty-apps/community/apollo-enrich/src/fields/apollo-industry.field.ts

@@ -0,0 +1,16 @@
+import {
+  defineField,
+  FieldType,
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
+} from 'twenty-sdk';
+
+export default defineField({
+  universalIdentifier: '505532f5-1fc5-4a58-8074-ba9b48650dbc',
+  objectUniversalIdentifier:
+    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
+  type: FieldType.TEXT,
+  name: 'apolloIndustry',
+  label: 'Apollo Industry',
+  description: 'Industry classification from Apollo enrichment',
+  icon: 'IconBuildingFactory',
+});

packages/twenty-apps/community/apollo-enrich/src/fields/apollo-short-description.field.ts

@@ -0,0 +1,16 @@
+import {
+  defineField,
+  FieldType,
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
+} from 'twenty-sdk';
+
+export default defineField({
+  universalIdentifier: 'be15e062-b065-48b4-979c-65b9a50e0cb1',
+  objectUniversalIdentifier:
+    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
+  type: FieldType.TEXT,
+  name: 'apolloShortDescription',
+  label: 'Apollo Description',
+  description: 'Short company description from Apollo enrichment',
+  icon: 'IconFileDescription',
+});

packages/twenty-apps/community/apollo-enrich/src/fields/apollo-total-funding.field.ts

@@ -0,0 +1,16 @@
+import {
+  defineField,
+  FieldType,
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
+} from 'twenty-sdk';
+
+export default defineField({
+  universalIdentifier: 'c90ae72d-4ddf-4f22-882f-eef98c91e40e',
+  objectUniversalIdentifier:
+    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
+  type: FieldType.CURRENCY,
+  name: 'apolloTotalFunding',
+  label: 'Total Funding',
+  description: 'Total funding raised by the company, from Apollo enrichment',
+  icon: 'IconCash',
+});

packages/twenty-apps/community/apollo-enrich/src/front-components/apollo-oauth-cta.tsx

@@ -0,0 +1,220 @@
+import styled from '@emotion/styled';
+import { useEffect, useState } from 'react';
+import { OAuthApplicationVariables } from 'src/logic-functions/get-oauth-application-variables';
+import { VERIFY_PAGE_PATH } from 'src/logic-functions/get-verify-page';
+import { defineFrontComponent } from 'twenty-sdk';
+
+const StyledContainer = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  width: 100%;
+`;
+
+const StyledSectionTitle = styled.h3`
+  color: #333;
+  font-family: 'Inter', sans-serif;
+  font-size: 15px;
+  font-weight: 600;
+  margin: 0 0 4px 0;
+`;
+
+const StyledSectionSubtitle = styled.p`
+  color: #818181;
+  font-family: 'Inter', sans-serif;
+  font-size: 13px;
+  font-weight: 400;
+  margin: 0 0 12px 0;
+`;
+
+const StyledCard = styled.div`
+  align-items: center;
+  background: #fff;
+  border: 1px solid #ebebeb;
+  border-radius: 8px;
+  display: flex;
+  gap: 12px;
+  padding: 16px;
+`;
+
+const StyledIconContainer = styled.div`
+  align-items: center;
+  background: #f5f5f5;
+  border-radius: 8px;
+  color: #666;
+  display: flex;
+  flex-shrink: 0;
+  height: 40px;
+  justify-content: center;
+  width: 40px;
+`;
+
+const StyledTextContainer = styled.div`
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
+`;
+
+const StyledTitle = styled.span`
+  color: #333;
+  font-family: 'Inter', sans-serif;
+  font-size: 14px;
+  font-weight: 500;
+`;
+
+const StyledDescription = styled.span`
+  color: #818181;
+  font-family: 'Inter', sans-serif;
+  font-size: 13px;
+`;
+
+const StyledLink = styled.a`
+  align-items: center;
+  background: #5e5adb;
+  border: 1px solid rgba(0, 0, 0, 0.04);
+  border-radius: 4px;
+  box-sizing: border-box;
+  color: #fafafa;
+  cursor: pointer;
+  display: inline-flex;
+  flex-shrink: 0;
+  font-family: 'Inter', sans-serif;
+  font-size: 13px;
+  font-weight: 500;
+  gap: 4px;
+  height: 32px;
+  justify-content: center;
+  padding: 0 12px;
+  text-decoration: none;
+  transition: background 0.1s ease;
+  white-space: nowrap;
+
+  &:hover {
+    background: #4b47b8;
+  }
+
+  &:active {
+    background: #3c3996;
+  }
+
+  &:focus {
+    outline: none;
+  }
+`;
+
+const StyledConnectedStatus = styled.span`
+  align-items: center;
+  background: #10b981;
+  border-radius: 4px;
+  color: #fff;
+  display: inline-flex;
+  flex-shrink: 0;
+  font-family: 'Inter', sans-serif;
+  font-size: 13px;
+  font-weight: 500;
+  gap: 6px;
+  height: 32px;
+  padding: 0 12px;
+  white-space: nowrap;
+`;
+
+const StyledIcon = styled.img`
+  height: 24px;
+  width: 24px;
+`;
+
+const APOLLO_ICON_URL = 'https://twenty-icons.com/apollo.io';
+
+const fetchOAuthApplicationVariables = async (): Promise<OAuthApplicationVariables> => {
+  const backEndUrl = `${process.env.TWENTY_API_URL}/s/oauth/application-variables`;
+  const response = await fetch(backEndUrl, {
+    method: 'GET',
+  });
+  const data = await response.json();
+
+  return data;
+};
+
+const buildOAuthUrl = (oauthApplicationVariables: OAuthApplicationVariables): string => {
+  const { apolloOAuthUrl, apolloClientId, apolloRegisteredUrl } = oauthApplicationVariables;
+  const redirectUri = `${apolloRegisteredUrl}auth/oauth-propagator/callback`;
+  const state = encodeURIComponent(`${process.env.TWENTY_API_URL}/s${VERIFY_PAGE_PATH}`);
+  return `${apolloOAuthUrl}?client_id=${apolloClientId}&redirect_uri=${redirectUri}&state=${state}&response_type=code`;
+};
+
+const ApolloOAuthCta = () => {
+  const [oauthApplicationVariables, setOAuthApplicationVariables] =
+    useState<OAuthApplicationVariables | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    fetchOAuthApplicationVariables()
+      .then(setOAuthApplicationVariables)
+      .catch(setError)
+      .finally(() => setIsLoading(false));
+  }, []);
+
+  if (isLoading) {
+    return (
+      <StyledContainer>
+        <StyledSectionTitle>Connect to Apollo</StyledSectionTitle>
+        <StyledSectionSubtitle>Enrich your contacts with Apollo data</StyledSectionSubtitle>
+        <StyledCard>
+          <StyledIconContainer>
+            <StyledIcon src={APOLLO_ICON_URL} alt="Apollo" />
+          </StyledIconContainer>
+          <StyledTextContainer>
+            <StyledTitle>Apollo OAuth</StyledTitle>
+            <StyledDescription>Loading...</StyledDescription>
+          </StyledTextContainer>
+        </StyledCard>
+      </StyledContainer>
+    );
+  }
+
+  if (error || !oauthApplicationVariables) {
+    return null;
+  }
+
+  const isConnected = Boolean(oauthApplicationVariables.apolloAccessToken);
+  const oauthUrl = buildOAuthUrl(oauthApplicationVariables);
+
+  return (
+    <StyledContainer>
+      <StyledSectionTitle>Connect to Apollo</StyledSectionTitle>
+      <StyledSectionSubtitle>Enrich your contacts with Apollo data</StyledSectionSubtitle>
+      <StyledCard>
+        <StyledIconContainer>
+          <StyledIcon src={APOLLO_ICON_URL} alt="Apollo" />
+        </StyledIconContainer>
+        <StyledTextContainer>
+          <StyledTitle>Apollo OAuth</StyledTitle>
+          <StyledDescription>
+            {isConnected
+              ? 'Your Apollo account is connected'
+              : 'Connect your Apollo account to enrich contacts'}
+          </StyledDescription>
+        </StyledTextContainer>
+        {isConnected ? (
+          <StyledConnectedStatus>
+            ✓ Connected
+          </StyledConnectedStatus>
+        ) : (
+          <StyledLink href={oauthUrl} rel="noopener noreferrer">
+            Connect
+          </StyledLink>
+        )}
+      </StyledCard>
+    </StyledContainer>
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: '50d59f7c-eada-4731-aacd-8e45371e1040',
+  name: 'apollo-oauth-cta',
+  description: 'CTA button to connect to Apollo Enrichment via OAuth',
+  component: ApolloOAuthCta,
+});

packages/twenty-apps/community/apollo-enrich/src/logic-functions/get-authentication-token-pairs.ts

@@ -0,0 +1,96 @@
+import { defineLogicFunction, RoutePayload } from "twenty-sdk";
+import { MetadataApiClient } from 'twenty-sdk/generated';
+
+export const OAUTH_TOKEN_PAIRS_PATH = '/oauth/token-pairs';
+
+type ApolloTokenResponse = {
+  access_token: string;
+  token_type: string;
+  expires_in: number;
+  refresh_token: string;
+  scope: string;
+  created_at: number;
+};
+
+const getAuthenticationTokenPairs = async (
+  code: string,
+  clientId: string,
+  clientSecret: string,
+): Promise<ApolloTokenResponse> => {
+  const formData = new URLSearchParams({
+    grant_type: 'authorization_code',
+    client_id: clientId,
+    client_secret: clientSecret,
+    code: code,
+    redirect_uri: 'https://hjsm0q38-3000.uks1.devtunnels.ms/auth/oauth-propagator/callback',
+  });
+
+  const response = await fetch('https://app.apollo.io/api/v1/oauth/token', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+    },
+    body: formData.toString(),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`Failed to exchange code for tokens: ${response.status} - ${errorText}`);
+  }
+
+  return response.json();
+};
+
+const handler = async (event: RoutePayload): Promise<any> => {
+  const { queryStringParameters: { code } } = event;
+
+  if (!code) {
+    throw new Error('Code is required');
+  }
+
+  const apolloClientId = process.env.APOLLO_CLIENT_ID ?? '';
+  const apolloClientSecret = process.env.APOLLO_CLIENT_SECRET ?? '';
+  const applicationId = process.env.APPLICATION_ID ?? '';
+
+  const metadataClient = new MetadataApiClient({});
+
+  const tokenPairs = await getAuthenticationTokenPairs(
+    code,
+    apolloClientId,
+    apolloClientSecret,
+  );
+
+  await metadataClient.mutation({
+    updateOneApplicationVariable: {
+      __args: {
+          key: 'APOLLO_ACCESS_TOKEN',
+          value: tokenPairs.access_token,
+          applicationId,
+        },
+    },
+  });
+
+   await metadataClient.mutation({
+    updateOneApplicationVariable: {
+      __args: {
+          key: 'APOLLO_REFRESH_TOKEN',
+          value: tokenPairs.refresh_token,
+          applicationId,
+        },
+    },
+  });
+  return {tokenPairs};
+};
+
+export default defineLogicFunction({
+  universalIdentifier: '7ccc63a7-ece1-44c0-adbe-805a1baea03a',
+  name: 'get-authentication-token-pairs',
+  description: 'Returns the Apollo authentication token pairs',
+  timeoutSeconds: 10,
+  handler,
+  httpRouteTriggerSettings: {
+    path: OAUTH_TOKEN_PAIRS_PATH,
+    httpMethod: 'GET',
+    isAuthRequired: false,
+  },
+});

packages/twenty-apps/community/apollo-enrich/src/logic-functions/get-oauth-application-variables.ts

@@ -0,0 +1,32 @@
+import { defineLogicFunction } from 'twenty-sdk';
+
+export type OAuthApplicationVariables = {
+  apolloClientId: string;
+  apolloRegisteredUrl: string;
+  apolloOAuthUrl: string;
+  apolloAccessToken: string;
+  apolloRefreshToken: string;
+};
+
+const handler = async (): Promise<OAuthApplicationVariables> => {
+  const apolloClientId = process.env.APOLLO_CLIENT_ID ?? '';
+  const apolloRegisteredUrl = process.env.APOLLO_REGISTERED_URL ?? '';
+  const apolloOAuthUrl = process.env.APOLLO_OAUTH_URL ?? '';
+  const apolloAccessToken = process.env.APOLLO_ACCESS_TOKEN ?? '';
+  const apolloRefreshToken = process.env.APOLLO_REFRESH_TOKEN ?? '';
+
+  return { apolloClientId, apolloRegisteredUrl, apolloOAuthUrl, apolloAccessToken, apolloRefreshToken };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: 'b7c3e8f1-9d4a-4e2b-8f6c-1a5d3e7b9c2f',
+  name: 'get-oauth-application-variables',
+  description: 'Returns the Apollo OAuth authorization URL',
+  timeoutSeconds: 10,
+  handler,
+  httpRouteTriggerSettings: {
+    path: '/oauth/application-variables',
+    httpMethod: 'GET',
+    isAuthRequired: false,
+  },
+});

packages/twenty-apps/community/apollo-enrich/src/logic-functions/get-verify-page.ts

@@ -0,0 +1,90 @@
+import { defineLogicFunction } from "twenty-sdk";
+
+export const VERIFY_PAGE_PATH = '/oauth/verify';
+
+const buildVerifyPageHtml = (applicationId: string): string => `<!DOCTYPE html>
+<html>
+<head>
+  <title>Apollo OAuth - Verifying...</title>
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; max-width: 600px; margin: 50px auto; padding: 20px; text-align: center; }
+    .loading { color: #6b7280; }
+    .success { color: #10b981; }
+    .error { color: #ef4444; }
+    .spinner { border: 3px solid #f3f4f6; border-top: 3px solid #3b82f6; border-radius: 50%; width: 40px; height: 40px; animation: spin 1s linear infinite; margin: 20px auto; }
+    @keyframes spin { 0% { transform: rotate(0deg); } 100% { transform: rotate(360deg); } }
+  </style>
+  <script>
+    (async function() {
+      const applicationId = ${JSON.stringify(applicationId)};
+      const urlParams = new URLSearchParams(window.location.search);
+      const code = urlParams.get('code');
+      const baseUrl = window.location.origin;
+
+      function showError(message) {
+        document.addEventListener('DOMContentLoaded', function() {
+          document.getElementById('spinner').style.display = 'none';
+          document.getElementById('title').textContent = '✗ Connection Failed';
+          document.getElementById('title').className = 'error';
+          document.getElementById('status').textContent = message;
+        });
+
+        if (window.opener) {
+          window.opener.postMessage({ type: 'APOLLO_OAUTH_ERROR', error: message }, '*');
+        }
+      }
+
+      if (!code) {
+        showError('Authorization code is missing. Please try connecting again.');
+        return;
+      }
+
+      try {
+        const response = await fetch(
+          baseUrl + '/s/oauth/token-pairs?code=' + encodeURIComponent(code),
+          {
+            method: 'GET',
+            headers: { 'Content-Type': 'application/json' }
+          }
+        );
+
+        if (!response.ok) {
+          const errorText = await response.text();
+          throw new Error('Failed to get tokens: ' + response.status + ' - ' + errorText);
+        }
+
+        const tokens = await response.json();
+
+        window.location.href = 'http://apple.localhost:3001/settings/applications/' + applicationId + '#custom';
+
+      } catch (error) {
+        showError(error.message);
+      }
+    })();
+  </script>
+</head>
+<body>
+  <div class="spinner" id="spinner"></div>
+  <h1 class="loading" id="title">Connecting to Apollo...</h1>
+  <p id="status">Please wait while we complete the connection.</p>
+</body>
+</html>`;
+
+const handler = async (): Promise<string> => {
+  const applicationId = process.env.APPLICATION_ID ?? '';
+
+  return buildVerifyPageHtml(applicationId);
+};
+
+export default defineLogicFunction({
+  universalIdentifier: '4d74950a-d9c1-4c66-a799-89c1aea4e6b0',
+  name: 'get-verify-page',
+  description: 'Returns the Apollo OAuth verify page',
+  timeoutSeconds: 10,
+  handler,
+  httpRouteTriggerSettings: {
+    path: VERIFY_PAGE_PATH,
+    httpMethod: 'GET',
+    isAuthRequired: false,
+  },
+});

packages/twenty-apps/community/apollo-enrich/src/logic-functions/on-company-updated.ts

@@ -0,0 +1,227 @@
+import {
+  defineLogicFunction,
+  type DatabaseEventPayload,
+  type ObjectRecordUpdateEvent,
+} from 'twenty-sdk';
+import { CoreApiClient } from 'twenty-sdk/generated';
+
+type CompanyRecord = {
+  id: string;
+  name?: string;
+  domainName?: {
+    primaryLinkUrl?: string;
+    primaryLinkLabel?: string;
+  };
+};
+
+type ApolloOrganization = {
+  name?: string;
+  website_url?: string;
+  linkedin_url?: string;
+  twitter_url?: string;
+  estimated_num_employees?: number;
+  annual_revenue?: number;
+  total_funding?: number;
+  street_address?: string;
+  city?: string;
+  state?: string;
+  postal_code?: string;
+  country?: string;
+  short_description?: string;
+  industry?: string;
+  founded_year?: number;
+};
+
+type ApolloEnrichResponse = {
+  organization?: ApolloOrganization;
+};
+
+const extractDomain = (
+  domainName?: CompanyRecord['domainName'],
+): string | undefined => {
+  const url = domainName?.primaryLinkUrl;
+
+  if (!url) {
+    return undefined;
+  }
+
+  try {
+    const hostname = new URL(
+      url.startsWith('http') ? url : `https://${url}`,
+    ).hostname;
+
+    return hostname.replace(/^www\./, '');
+  } catch {
+    return url.replace(/^(https?:\/\/)?(www\.)?/, '').split('/')[0];
+  }
+};
+
+const fetchApolloEnrichment = async (
+  domain: string,
+): Promise<ApolloOrganization | undefined> => {
+  const response = await fetch(
+    `https://api.apollo.io/api/v1/organizations/enrich?domain=${encodeURIComponent(domain)}`,
+    {
+      method: 'GET',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${process.env.APOLLO_ACCESS_TOKEN ?? ''}`,
+      },
+    },
+  );
+
+  const data: ApolloEnrichResponse = await response.json();
+
+  return data.organization;
+};
+
+const buildCompanyUpdateData = (
+  apolloOrganization: ApolloOrganization,
+): Record<string, unknown> => {
+  const updateData: Record<string, unknown> = {};
+
+  if (apolloOrganization.name) {
+    updateData.name = apolloOrganization.name;
+  }
+
+  if (apolloOrganization.estimated_num_employees) {
+    updateData.employees = apolloOrganization.estimated_num_employees;
+  }
+
+  if (apolloOrganization.linkedin_url) {
+    updateData.linkedinLink = {
+      primaryLinkUrl: apolloOrganization.linkedin_url,
+      primaryLinkLabel: 'LinkedIn',
+    };
+  }
+
+  if (apolloOrganization.twitter_url) {
+    updateData.xLink = {
+      primaryLinkUrl: apolloOrganization.twitter_url,
+      primaryLinkLabel: 'X',
+    };
+  }
+
+  if (apolloOrganization.annual_revenue) {
+    updateData.annualRecurringRevenue = {
+      amountMicros: apolloOrganization.annual_revenue * 1_000_000,
+      currencyCode: 'USD',
+    };
+  }
+
+  const hasAddress =
+    apolloOrganization.street_address ||
+    apolloOrganization.city ||
+    apolloOrganization.state ||
+    apolloOrganization.country;
+
+  if (hasAddress) {
+    updateData.address = {
+      addressStreet1: apolloOrganization.street_address ?? '',
+      addressCity: apolloOrganization.city ?? '',
+      addressState: apolloOrganization.state ?? '',
+      addressPostcode: apolloOrganization.postal_code ?? '',
+      addressCountry: apolloOrganization.country ?? '',
+    };
+  }
+
+  if (apolloOrganization.industry) {
+    updateData.apolloIndustry = apolloOrganization.industry;
+  }
+
+  if (apolloOrganization.short_description) {
+    updateData.apolloShortDescription = apolloOrganization.short_description;
+  }
+
+  if (apolloOrganization.founded_year) {
+    updateData.apolloFoundedYear = apolloOrganization.founded_year;
+  }
+
+  if (apolloOrganization.total_funding) {
+    updateData.apolloTotalFunding = {
+      amountMicros: apolloOrganization.total_funding * 1_000_000,
+      currencyCode: 'USD',
+    };
+  }
+
+  return updateData;
+};
+
+const updateCompanyInTwenty = async (
+  companyId: string,
+  updateData: Record<string, unknown>,
+): Promise<void> => {
+  const client = new CoreApiClient();
+
+  const result = await client.mutation({
+    updateCompany: {
+      __args: {
+        id: companyId,
+        data: updateData,
+      },
+      id: true,
+    },
+  });
+
+  if (!result.updateCompany) {
+    throw new Error(`Failed to update company ${companyId}: no result`);
+  }
+};
+
+type CompanyUpdateEvent = DatabaseEventPayload<
+  ObjectRecordUpdateEvent<CompanyRecord>
+>;
+
+const handler = async (
+  event: CompanyUpdateEvent,
+): Promise<object | undefined> => {
+
+    const { recordId, properties } = event;
+    const { after: companyAfter } = properties;
+
+    const domain = extractDomain(companyAfter?.domainName);
+
+    if (!domain) {
+      return { skipped: true, reason: 'no domain found on company' };
+    }
+
+    const apolloOrganization = await fetchApolloEnrichment(domain);
+
+    if (!apolloOrganization) {
+      return {
+        skipped: true,
+        reason: `no Apollo data found for ${domain}`,
+      };
+    }
+
+    const updateData = buildCompanyUpdateData(apolloOrganization);
+
+    if (Object.keys(updateData).length === 0) {
+      return { skipped: true, reason: 'no enrichment data to apply' };
+    }
+
+    await updateCompanyInTwenty(recordId, updateData);
+
+    const result = {
+      enriched: true,
+      companyId: recordId,
+      domain,
+      updatedFields: Object.keys(updateData),
+    };
+
+    return result;
+
+};
+
+export default defineLogicFunction({
+  universalIdentifier: '6248b3fe-a8af-404a-8e38-19df98f73d81',
+  name: 'on-company-updated',
+  description:
+    'Enriches company data from Apollo when the company domain is updated',
+  timeoutSeconds: 30,
+  handler,
+  databaseEventTriggerSettings: {
+    eventName: 'company.updated',
+    updatedFields: ['domainName'],
+  },
+});

packages/twenty-apps/community/apollo-enrich/src/logic-functions/post-install.ts

@@ -0,0 +1,13 @@
+import { definePostInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk';
+
+const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
+  console.log('Post install logic function executed successfully!', payload.previousVersion);
+};
+
+export default definePostInstallLogicFunction({
+  universalIdentifier: '08292efc-d7ba-4ec3-ab95-e7c33bd3a3bc',
+  name: 'post-install',
+  description: 'Runs after installation to set up the application.',
+  timeoutSeconds: 300,
+  handler,
+});

packages/twenty-apps/community/apollo-enrich/src/logic-functions/pre-install.ts

@@ -0,0 +1,13 @@
+import { definePreInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk';
+
+const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
+  console.log('Pre install logic function executed successfully!', payload.previousVersion);
+};
+
+export default definePreInstallLogicFunction({
+  universalIdentifier: 'af7cd86e-149e-466a-8d60-312b6e46d604',
+  name: 'pre-install',
+  description: 'Runs before installation to prepare the application.',
+  timeoutSeconds: 300,
+  handler,
+});

packages/twenty-apps/community/apollo-enrich/src/roles/default-role.ts

@@ -0,0 +1,15 @@
+import { defineRole } from 'twenty-sdk';
+
+export const DEFAULT_ROLE_UNIVERSAL_IDENTIFIER =
+  'b8faae3f-e174-43fa-ab94-715712ae26cb';
+
+export default defineRole({
+  universalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+  label: 'Apollo enrich default function role',
+  description: 'Apollo enrich default function role',
+  canReadAllObjectRecords: true,
+  canUpdateAllObjectRecords: true,
+  canSoftDeleteAllObjectRecords: true,
+  canDestroyAllObjectRecords: false,
+  canUpdateAllSettings: true,
+});

packages/twenty-apps/community/apollo-enrich/tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "compileOnSave": false,
+  "compilerOptions": {
+    "sourceMap": true,
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": ".",
+    "jsx": "react-jsx",
+    "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "importHelpers": true,
+    "allowUnreachableCode": false,
+    "strict": true,
+    "alwaysStrict": true,
+    "noImplicitAny": true,
+    "strictBindCallApply": false,
+    "target": "es2018",
+    "module": "esnext",
+    "lib": ["es2020", "dom"],
+    "skipLibCheck": true,
+    "skipDefaultLibCheck": true,
+    "resolveJsonModule": true,
+    "paths": {
+      "src/*": ["./src/*"],
+      "~/*": ["./*"]
+    }
+  },
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}

packages/twenty-apps/community/fireflies/scripts/fetch-all-meetings.ts

@@ -219,4 +219,3 @@ main().catch((error) => {
   process.exit(1);
 });
 
-

packages/twenty-apps/community/fireflies/src/__tests__/historical-importer.spec.ts

@@ -81,4 +81,3 @@ describe('HistoricalImporter', () => {
   });
 });
 
-

packages/twenty-apps/community/fireflies/src/historical-importer.ts

@@ -158,4 +158,3 @@ export class HistoricalImporter {
   }
 }
 
-

packages/twenty-apps/community/fireflies/src/objects/index.ts

@@ -1,3 +1,2 @@
 export { Meeting } from './meeting';
 
-

packages/twenty-apps/community/fireflies/src/webhook-handler.ts

@@ -330,7 +330,6 @@ export class WebhookHandler {
     }
   }
 
-
   private async createFailedMeetingRecord(params: unknown, error: string): Promise<void> {
     try {
       const twentyApiKey = process.env.TWENTY_API_KEY || '';

packages/twenty-apps/community/linkedin-browser-extension/browser-extension/src/entrypoints/add-person.content/index.tsx

@@ -43,7 +43,6 @@ export default defineContentScript({
       },
     });
 
-
     ctx.addEventListener(window, 'wxt:locationchange', ({newUrl, }) => {
     const injectedBtn = document.querySelector('[data-id="twenty-btn"]');
         if(personPattern.includes(newUrl) && !injectedBtn) ui.mount();

packages/twenty-apps/community/linkedin-browser-extension/browser-extension/src/ui/components/button.tsx

@@ -8,7 +8,6 @@ const StyledButton = styled.button`
   --text-color: #0a66c2;
   --bg-color: #00000000;
 
-
   font-size: ${({theme}) => theme.spacing(3.5)};
   font-weight: ${({theme}) => theme.font.weight.semiBold};
   font-family: ${({theme}) => theme.font.family};
@@ -26,7 +25,6 @@ const StyledButton = styled.button`
   transition-timing-function: cubic-bezier(.4, 0, .2, 1);
   transition-duration: 167ms;
 
-
   &:hover {
     background-color: var(--hover-bg-color);
     color: var(--hover-color);

packages/twenty-apps/community/linkedin-browser-extension/browser-extension/src/ui/theme/context/ThemeContext.tsx

@@ -1,6 +1,5 @@
-import { ThemeProvider } from '@emotion/react';
 import type React from 'react';
-import { THEME_DARK, ThemeContextProvider } from 'twenty-ui/theme';
+import { ColorSchemeProvider } from 'twenty-ui/theme-constants';
 
 type ThemeContextProps = {
   children: React.ReactNode;
@@ -8,10 +7,6 @@ type ThemeContextProps = {
 
 export const ThemeContext = ({ children }: ThemeContextProps) => {
   return (
-      <ThemeProvider theme={THEME_DARK}>
-        <ThemeContextProvider theme={THEME_DARK}>
-          {children}
-        </ThemeContextProvider>
-      </ThemeProvider>
+    <ColorSchemeProvider colorScheme="dark">{children}</ColorSchemeProvider>
   );
 };

packages/twenty-apps/community/linkedin-browser-extension/browser-extension/src/ui/theme/emotion.d.ts

@@ -1,5 +0,0 @@
-import type { ThemeType } from 'twenty-ui/theme';
-
-declare module '@emotion/react' {
-  export interface Theme extends ThemeType {}
-}

packages/twenty-apps/hello-world/.env.example

@@ -1,2 +0,0 @@
-TWENTY_API_KEY=<SET_YOUR_TWENTY_API_KEY>
-TWENTY_API_URL=<SET_YOUR_TWENTY_API_URL>

packages/twenty-apps/hello-world/.gitignore

@@ -1,2 +1,38 @@
-.yarn/install-state.gz
-.env
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn
+
+# codegen
+generated
+
+# testing
+/coverage
+
+# dev
+/dist/
+
+.twenty
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# typescript
+*.tsbuildinfo
+*.d.ts