chore: move reference projects to their own repo (#3812)

The reference/example projects (`references/`) now live in their own
repo, https://github.com/triggerdotdev/references, so their heavy,
frequently-changing dependencies are no longer part of this repo's
lockfile and tooling. This removes them here and repoints everything
that referenced them.

- Deletes `references/`; updates the pnpm workspace + lockfile.
- Clears the references-only CI rules and `.vscode` configs.
- Repoints the docs (contributor/agent + one public page) to the new
repo.
- `seed.mts` keeps the local-dev projects (hello-world, d3-chat,
realtime-streams).

Author: nicktrn

.claude/rules/sdk-packages.md

@@ -9,4 +9,4 @@ paths:
 - Default to **patch**. Get maintainer approval for minor. Never select major without explicit approval.
 - `@trigger.dev/core`: **Never import the root**. Always use subpath imports (e.g., `@trigger.dev/core/v3`).
 - Do NOT update `rules/` or `.claude/skills/trigger-dev-tasks/` unless explicitly asked. These are maintained in separate dedicated passes.
-- Test changes using `references/hello-world` reference project.
+- Test changes using the `hello-world` project in the [`triggerdotdev/references`](https://github.com/triggerdotdev/references) repo.

.github/workflows/check-review-md.yml

@@ -7,7 +7,6 @@ on:
       - "docs/**"
       - ".changeset/**"
       - ".server-changes/**"
-      - "references/**"
 
 concurrency:
   group: review-md-drift-${{ github.event.pull_request.number }}

.github/workflows/claude-md-audit.yml

@@ -8,7 +8,6 @@ on:
       - ".changeset/**"
       - ".server-changes/**"
       - "**/*.md"
-      - "references/**"
 
 concurrency:
   group: claude-md-audit-${{ github.event.pull_request.number }}

.github/workflows/pr_checks.yml

@@ -39,7 +39,6 @@ jobs:
               - '!.changeset/**'
               - '!hosting/**'
               - '!.github/**'
-              - '!references/**'
               - '!**/*.md'
               - '!**/.env.example'
       - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1

.vscode/launch.json

@@ -47,78 +47,6 @@
       "url": "http://localhost:3030",
       "webRoot": "${workspaceFolder}/apps/webapp/app"
     },
-    {
-      "type": "node-terminal",
-      "request": "launch",
-      "name": "Debug V3 init CLI",
-      "command": "pnpm exec trigger init",
-      "cwd": "${workspaceFolder}/references/init-shell",
-      "sourceMaps": true
-    },
-    {
-      "type": "node-terminal",
-      "request": "launch",
-      "name": "Debug V3 init dev CLI",
-      "command": "pnpm exec trigger dev",
-      "cwd": "${workspaceFolder}/references/init-shell",
-      "sourceMaps": true
-    },
-    {
-      "type": "node-terminal",
-      "request": "launch",
-      "name": "Debug V3 Dev CLI",
-      "command": "pnpm exec trigger dev",
-      "cwd": "${workspaceFolder}/references/hello-world",
-      "sourceMaps": true
-    },
-    {
-      "type": "node-terminal",
-      "request": "launch",
-      "name": "Debug Dev Next.js Realtime",
-      "command": "pnpm exec trigger dev",
-      "cwd": "${workspaceFolder}/references/nextjs-realtime",
-      "sourceMaps": true
-    },
-    {
-      "type": "node-terminal",
-      "request": "launch",
-      "name": "Debug prisma-catalog deploy CLI",
-      "command": "pnpm exec trigger deploy --self-hosted --load-image",
-      "cwd": "${workspaceFolder}/references/prisma-catalog",
-      "sourceMaps": true
-    },
-    {
-      "type": "node-terminal",
-      "request": "launch",
-      "name": "Debug V3 Deploy CLI",
-      "command": "pnpm exec trigger deploy --self-hosted --load-image",
-      "cwd": "${workspaceFolder}/references/hello-world",
-      "sourceMaps": true
-    },
-    {
-      "type": "node-terminal",
-      "request": "launch",
-      "name": "Debug V3 list-profiles CLI",
-      "command": "pnpm exec trigger list-profiles --log-level debug",
-      "cwd": "${workspaceFolder}/references/hello-world",
-      "sourceMaps": true
-    },
-    {
-      "type": "node-terminal",
-      "request": "launch",
-      "name": "Debug V3 update CLI",
-      "command": "pnpm exec trigger update",
-      "cwd": "${workspaceFolder}/references/hello-world",
-      "sourceMaps": true
-    },
-    {
-      "type": "node-terminal",
-      "request": "launch",
-      "name": "Debug V3 Management",
-      "command": "pnpm run management",
-      "cwd": "${workspaceFolder}/references/hello-world",
-      "sourceMaps": true
-    },
     {
       "type": "node",
       "request": "attach",
@@ -135,14 +63,6 @@
       "cwd": "${workspaceFolder}/packages/cli-v3",
       "sourceMaps": true
     },
-    {
-      "type": "node-terminal",
-      "request": "launch",
-      "name": "debug v3 hello-world dev",
-      "command": "pnpm exec trigger dev",
-      "cwd": "${workspaceFolder}/references/hello-world",
-      "sourceMaps": true
-    },
     {
       "type": "node-terminal",
       "request": "launch",
@@ -158,14 +78,6 @@
       "command": "pnpm run test ./src/run-queue/index.test.ts --run",
       "cwd": "${workspaceFolder}/internal-packages/run-engine",
       "sourceMaps": true
-    },
-    {
-      "type": "node-terminal",
-      "request": "launch",
-      "name": "Debug d3-demo",
-      "command": "pnpm exec trigger dev",
-      "cwd": "${workspaceFolder}/references/d3-demo",
-      "sourceMaps": true
     }
   ]
 }

.vscode/settings.json

@@ -1,5 +1,5 @@
 {
-  "deno.enablePaths": ["references/deno-reference", "runtime_tests/tests/deno"],
+  "deno.enablePaths": ["runtime_tests/tests/deno"],
   "debug.toolBarLocation": "commandCenter",
   "typescript.tsdk": "node_modules/typescript/lib",
   "search.exclude": {

AGENTS.md

@@ -7,7 +7,7 @@ This repository is a pnpm monorepo managed with Turbo. It contains multiple apps
 - `apps/supervisor` – Node application for executing built tasks.
 - `packages/*` – Published packages such as `@trigger.dev/sdk`, the CLI (`trigger.dev`), and shared libraries.
 - `internal-packages/*` – Internal-only packages used by the webapp and other apps.
-- `references/*` – Example projects for manual testing and development of new features.
+- Example/reference projects for manual testing live in a separate repo: [`triggerdotdev/references`](https://github.com/triggerdotdev/references).
 - `ai/references` – Contains additional documentation including an overview (`repo.md`) and testing guidelines (`tests.md`).
 
 See `ai/references/repo.md` for a more complete explanation of the workspaces.
@@ -65,5 +65,5 @@ Refer to `ai/references/tests.md` for details on writing tests. Tests should avo
   ```bash
   pnpm run dev --filter docs
   ```
-- `references/README.md` explains how to create new reference projects for manual testing.
+- The [`triggerdotdev/references`](https://github.com/triggerdotdev/references) repo's README explains how to create new reference projects for manual testing.
 

CLAUDE.md

@@ -138,7 +138,7 @@ Docs live in `docs/` as a Mintlify site (MDX format). See `docs/CLAUDE.md` for c
 
 ### Reference Projects
 
-The `references/` directory contains test workspaces for testing SDK and platform features. Use `references/hello-world` to manually test changes before submitting PRs.
+Reference/example projects for testing SDK and platform features live in a separate repo: [`triggerdotdev/references`](https://github.com/triggerdotdev/references). Clone it alongside this repo and use its `projects/hello-world` to manually test changes before submitting PRs. See that repo's README for setup and linking to a local monorepo build.
 
 ## Docker Image Guidelines
 
@@ -167,15 +167,17 @@ export const myTask = task({
 
 The `rules/` directory contains versioned SDK documentation distributed via the SDK installer. Current version: `rules/manifest.json`. Do NOT update `rules/` or `.claude/skills/trigger-dev-tasks/` unless explicitly asked - these are maintained in separate dedicated passes.
 
-## Testing with hello-world Reference Project
+## Testing with the hello-world Reference Project
+
+The reference projects live in the separate [`triggerdotdev/references`](https://github.com/triggerdotdev/references) repo - clone it alongside this repo.
 
 First-time setup:
 
-1. `pnpm run db:seed` to seed the database
-2. Build CLI: `pnpm run build --filter trigger.dev && pnpm i`
-3. Authorize: `cd references/hello-world && pnpm exec trigger login -a http://localhost:3030`
+1. `pnpm run db:seed` to seed the database (creates the References org + hello-world project)
+2. Build the CLI/packages you want to test: `pnpm run build --filter trigger.dev`
+3. In your `references` clone, follow its README to link to your local monorepo build, then authorize: `cd projects/hello-world && pnpm exec trigger login -a http://localhost:3030`
 
-Running: `cd references/hello-world && pnpm exec trigger dev`
+Running (from your `references` clone): `cd projects/hello-world && pnpm exec trigger dev`
 
 ## Local Task Testing Workflow
 
@@ -190,7 +192,8 @@ curl -s http://localhost:3030/healthcheck  # Verify running
 ### Step 2: Start Trigger Dev in Background
 
 ```bash
-cd references/hello-world && pnpm exec trigger dev
+# in your triggerdotdev/references clone
+cd projects/hello-world && pnpm exec trigger dev
 # Wait for "Local worker ready [node]"
 ```
 

CONTRIBUTING.md

@@ -107,24 +107,32 @@ branch are tagged into a release periodically.
 
 ## Manual testing using hello-world
 
-We use the `<root>/references/hello-world` subdirectory as a staging ground for testing changes to the SDK (`@trigger.dev/sdk` at `<root>/packages/trigger-sdk`), the Core package (`@trigger.dev/core` at `<root>packages/core`), the CLI (`trigger.dev` at `<root>/packages/cli-v3`) and the platform (The remix app at `<root>/apps/webapp`). The instructions below will get you started on using the `hello-world` for local development of Trigger.dev.
+The `hello-world` reference project (and the others) live in a separate repo:
+[`triggerdotdev/references`](https://github.com/triggerdotdev/references). Clone it
+alongside this repo. It's the staging ground for testing changes to the SDK
+(`@trigger.dev/sdk` at `<root>/packages/trigger-sdk`), the Core package
+(`@trigger.dev/core` at `<root>/packages/core`), the CLI (`trigger.dev` at
+`<root>/packages/cli-v3`) and the platform (the Remix app at `<root>/apps/webapp`).
+To exercise your local monorepo changes, the reference project links to your local
+build — see the references repo's README for the `pnpm run link` flow.
+
+> Paths below such as `projects/hello-world` are relative to your `references`
+> clone, not this repo.
 
 ### First-time setup
 
 First, make sure you are running the webapp according to the instructions above. The seed step from setup already created a `hello-world` project under the `References` org with the stable ref `proj_rrkpdguyagvsoktglnod` — log in at http://localhost:3030 with any email to access it. Then:
 
-1. Build the CLI (skip if you already ran the build step in setup)
+1. Build the CLI and packages (skip if you already ran the build step in setup)
 
 ```sh
-pnpm run build --filter trigger.dev
-# Make it accessible to `pnpm exec`
-pnpm i
+pnpm run build --filter trigger.dev --filter "@trigger.dev/*"
 ```
 
-2. Change into the `<root>/references/hello-world` directory and authorize the CLI to the local server:
+2. In your `references` clone, link to your local monorepo build (see its README), then change into `projects/hello-world` and authorize the CLI to the local server:
 
 ```sh
-cd references/hello-world
+cd projects/hello-world
 cp .env.example .env
 pnpm exec trigger login -a http://localhost:3030
 ```
@@ -134,7 +142,7 @@ This will open a new browser window and authorize the CLI against your local use
 You can optionally pass a `--profile` flag to the `login` command, which will allow you to use the CLI with separate accounts/servers. We suggest using a profile called `local` for your local development:
 
 ```sh
-cd references/hello-world
+cd projects/hello-world
 pnpm exec trigger login -a http://localhost:3030 --profile local
 # later when you run the dev or deploy command:
 pnpm exec trigger dev --profile local
@@ -147,35 +155,35 @@ The following steps should be followed any time you start working on a new featu
 
 1. Make sure the webapp is running on localhost:3030
 
-2. Open a terminal window and build the CLI and packages and watch for changes
+2. In this repo, open a terminal window and build the CLI and packages and watch for changes (the reference project links against this build)
 
 ```sh
 pnpm run dev --filter trigger.dev --filter "@trigger.dev/*"
 ```
 
-3. Open another terminal window, and change into the `<root>/references/hello-world` directory.
+3. Open another terminal window, and change into `projects/hello-world` in your `references` clone.
 
 4. Run the `dev` command, which will register all the local tasks with the platform and allow you to start testing task execution:
 
 ```sh
-# in <root>/references/hello-world
+# in <references-clone>/projects/hello-world
 pnpm exec trigger dev
 ```
 
 If you want additional debug logging, you can use the `--log-level debug` flag:
 
 ```sh
-# in <root>/references/hello-world
+# in <references-clone>/projects/hello-world
 pnpm exec trigger dev --log-level debug
 ```
 
-5. If you make any changes in the CLI/Core/SDK, you'll need to `CTRL+C` to exit the `dev` command and restart it to pickup changes. Any changes to the files inside of the `hello-world/src/trigger` dir will automatically be rebuilt by the `dev` command.
+5. If you make any changes in the CLI/Core/SDK, you'll need to `CTRL+C` to exit the `dev` command and restart it to pickup changes. Any changes to the files inside the reference project's `src/trigger` dir will automatically be rebuilt by the `dev` command.
 
 6. Navigate to the `hello-world` project in your local dashboard at localhost:3030 and you should see the list of tasks.
 
-7. Go to the "Test" page in the sidebar and select a task. Then enter a payload and click "Run test". You can tell what the payloads should be by looking at the relevant task file inside the `/references/hello-world/src/trigger` folder. Many of them accept an empty payload.
+7. Go to the "Test" page in the sidebar and select a task. Then enter a payload and click "Run test". You can tell what the payloads should be by looking at the relevant task file inside the reference project's `src/trigger` folder. Many of them accept an empty payload.
 
-8. Feel free to add additional files in `hello-world/src/trigger` to test out specific aspects of the system, or add in edge cases.
+8. Feel free to add additional files in the reference project's `src/trigger` dir to test out specific aspects of the system, or add in edge cases.
 
 ## Adding and running migrations
 

apps/webapp/seed.mts

@@ -53,7 +53,10 @@ async function seed() {
     console.log(`✅ Organization already exists: ${organization.title} (${organization.slug})`);
   }
 
-  // Define the reference projects with their specific project refs
+  // Reference projects with their specific project refs. These refs MUST stay in
+  // sync with the corresponding projects in the standalone references repo
+  // (github.com/triggerdotdev/references): hello-world hardcodes its ref in
+  // trigger.config.ts; d3-chat and realtime-streams read TRIGGER_PROJECT_REF.
   const referenceProjects = [
     {
       name: "hello-world",
@@ -82,9 +85,9 @@ async function seed() {
   console.log(`User: ${user.email}`);
   console.log(`Organization: ${organization.title} (${organization.slug})`);
   console.log(`Projects: ${referenceProjects.map((p) => p.name).join(", ")}`);
-  console.log("\n⚠️  Note: Update the .env files in d3-chat and realtime-streams with:");
-  console.log(`  - d3-chat: TRIGGER_PROJECT_REF=proj_cdmymsrobxmcgjqzhdkq`);
-  console.log(`  - realtime-streams: TRIGGER_PROJECT_REF=proj_klxlzjnzxmbgiwuuwhvb`);
+  console.log("\n⚠️  Note: in your triggerdotdev/references clone, set TRIGGER_PROJECT_REF in:");
+  console.log(`  - projects/d3-chat/.env: TRIGGER_PROJECT_REF=proj_cdmymsrobxmcgjqzhdkq`);
+  console.log(`  - projects/realtime-streams/.env: TRIGGER_PROJECT_REF=proj_klxlzjnzxmbgiwuuwhvb`);
 }
 
 async function createBatchLimitOrgs(user: User) {