diff --git a/.github/workflows/claude-md-audit.yml b/.github/workflows/claude-md-audit.yml index 883da3ee1e..42cfb96997 100644 --- a/.github/workflows/claude-md-audit.yml +++ b/.github/workflows/claude-md-audit.yml @@ -1,4 +1,4 @@ -name: 📝 CLAUDE.md Audit +name: 📝 Agent Instructions Audit on: pull_request: @@ -10,7 +10,7 @@ on: - "**/*.md" concurrency: - group: claude-md-audit-${{ github.event.pull_request.number }} + group: agent-instructions-audit-${{ github.event.pull_request.number }} cancel-in-progress: true jobs: @@ -48,29 +48,36 @@ jobs: --allowedTools "Read,Glob,Grep,Bash(git diff:*)" prompt: | - You are reviewing a PR to check whether any CLAUDE.md files or .claude/rules/ files need updating. + You are reviewing a PR to check whether any agent instruction files need updating. + + In this repo: + - Root shared agent guidance lives in `AGENTS.md`. + - Root `CLAUDE.md` is only a Claude Code adapter that imports `AGENTS.md`. + - Subdirectories may still have scoped `CLAUDE.md` files. + - `.claude/rules/` contains additional Claude Code guidance. ## Your task 1. Run `git diff origin/main...HEAD --name-only` to see which files changed in this PR. - 2. For each changed directory, check if there's a CLAUDE.md in that directory or a parent directory. - 3. Determine if any CLAUDE.md or .claude/rules/ file should be updated based on the changes. Consider: + 2. For each changed directory, check the applicable instruction files: root `AGENTS.md`, any `CLAUDE.md` in that directory or a parent directory, and relevant `.claude/rules/` files. + 3. Determine if any instruction file should be updated based on the changes. Consider: - New files/directories that aren't covered by existing documentation - - Changed architecture or patterns that contradict current CLAUDE.md guidance - - New dependencies, services, or infrastructure that Claude should know about - - Renamed or moved files that are referenced in CLAUDE.md + - Changed architecture or patterns that contradict current agent guidance + - New dependencies, services, or infrastructure that agents should know about + - Renamed or moved files that are referenced in an instruction file - Changes to build commands, test patterns, or development workflows ## Response format If NO updates are needed, respond with exactly: - ✅ CLAUDE.md files look current for this PR. + ✅ Agent instruction files look current for this PR. If updates ARE needed, respond with a short list: - 📝 **CLAUDE.md updates suggested:** + 📝 **Agent instruction updates suggested:** + - `AGENTS.md`: [what should be added/changed] - `path/to/CLAUDE.md`: [what should be added/changed] - `.claude/rules/file.md`: [what should be added/changed] - Keep suggestions specific and brief. Only flag things that would actually mislead Claude in future sessions. + Keep suggestions specific and brief. Only flag things that would actually mislead agents in future sessions. Do NOT suggest updates for trivial changes (bug fixes, small refactors within existing patterns). - Do NOT suggest creating new CLAUDE.md files - only updates to existing ones. + Do NOT suggest creating new CLAUDE.md files - only updates to existing instruction files. diff --git a/AGENTS.md b/AGENTS.md index b40705a956..a51faebbcd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,69 +1,274 @@ -# Guidance for Coding Agents - -This repository is a pnpm monorepo managed with Turbo. It contains multiple apps and packages that make up the Trigger.dev platform and SDK. - -## Repository layout -- `apps/webapp` – Remix application that serves as the main API and dashboard. -- `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. -- 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. - -## Development setup -1. Install dependencies with `pnpm i` (pnpm `10.33.2` and Node.js `22.23.1` are required). -2. Copy `.env.example` to `.env` and generate a random 16 byte hex string for `ENCRYPTION_KEY` (`openssl rand -hex 16`). Update other secrets if needed. -3. Start the local services with Docker: - ```bash - pnpm run docker - ``` - Add `:full` (`pnpm run docker:full`) for the optional observability + chaos tooling. See `docker/docker-compose.extras.yml`. -4. Run database migrations: - ```bash - pnpm run db:migrate - ``` -5. Build the webapp, CLI and SDK packages: - ```bash - pnpm run build --filter webapp && pnpm run build --filter trigger.dev && pnpm run build --filter @trigger.dev/sdk - ``` -6. Launch the development server: - ```bash - pnpm run dev --filter webapp - ``` - The webapp runs on . - -For full setup instructions see `CONTRIBUTING.md`. - -## Running tests -- Unit tests use **vitest**. Run all tests: - ```bash - pnpm run test - ``` -- Run tests for a specific workspace (example for `webapp`): - ```bash - pnpm run test --filter webapp - ``` -- Prefer running a single test file from within its directory: - ```bash - cd apps/webapp - pnpm run test ./src/components/Button.test.ts - ``` - If packages in that workspace need to be built first, run `pnpm run build --filter webapp`. - -Refer to `ai/references/tests.md` for details on writing tests. Tests should avoid mocks or stubs and use the helpers from `@internal/testcontainers` when Redis or Postgres are needed. - -## Coding style -- Formatting is enforced using oxfmt. Run `pnpm run format` before committing. -- Follow the existing project conventions. Test files live beside the files under test and use descriptive `describe` and `it` blocks. -- Do not commit directly to the `main` branch. All changes should be made in a separate branch and go through a pull request. - -## Additional docs -- The root `README.md` describes Trigger.dev and links to documentation. -- The `docs` workspace contains our documentation site, which can be run locally with: - ```bash - pnpm run dev --filter docs - ``` -- The [`triggerdotdev/references`](https://github.com/triggerdotdev/references) repo's README explains how to create new reference projects for manual testing. +# AGENTS.md +This file provides guidance to Claude Code when working with this repository. Subdirectory CLAUDE.md files provide deeper context when you navigate into specific areas. + +## Build and Development Commands + +This is a pnpm 10.33.2 monorepo using Turborepo. Run commands from root with `pnpm run`. + +**Adding dependencies:** Edit `package.json` directly instead of using `pnpm add`, then run `pnpm i` from the repo root. See `.claude/rules/package-installation.md` for the full process. + +```bash +pnpm run docker # Core dev services (Postgres, Redis, Electric, MinIO, ClickHouse, s2-lite) +# pnpm run docker:full # Same + observability stack (Prometheus, Grafana, OTEL) and chaos tooling +pnpm run db:migrate # Run database migrations +pnpm run db:seed # Seed the database (required for reference projects) + +# Build packages (required before running) +pnpm run build --filter webapp && pnpm run build --filter trigger.dev && pnpm run build --filter @trigger.dev/sdk + +pnpm run dev --filter webapp # Run webapp (http://localhost:3030) +pnpm run dev --filter trigger.dev --filter "@trigger.dev/*" # Watch CLI and packages +``` + +### Verifying Changes + +The verification command depends on where the change lives: + +- **Apps and internal packages** (`apps/*`, `internal-packages/*`): Use `typecheck`. **Never use `build`** for these — building proves almost nothing about correctness. +- **Public packages** (`packages/*`): Use `build`. + +```bash +# Apps and internal packages — use typecheck +pnpm run typecheck --filter webapp # ~1-2 minutes +pnpm run typecheck --filter @internal/run-engine + +# Public packages — use build +pnpm run build --filter @trigger.dev/sdk +pnpm run build --filter @trigger.dev/core +``` + +Only run typecheck/build after major changes (new files, significant refactors, schema changes). For small edits, trust the types and let CI catch issues. + +## Testing + +We use vitest exclusively. **Never mock anything** - use testcontainers instead. + +```bash +pnpm run test --filter webapp # All tests for a package +cd internal-packages/run-engine +pnpm run test ./src/engine/tests/ttl.test.ts --run # Single test file +pnpm run build --filter @internal/run-engine # May need to build deps first +``` + +Test files go next to source files (e.g., `MyService.ts` -> `MyService.test.ts`). + +### Testcontainers for Redis/PostgreSQL + +```typescript +import { redisTest, postgresTest, containerTest } from "@internal/testcontainers"; + +redisTest("should use redis", async ({ redisOptions }) => { + /* ... */ +}); +postgresTest("should use postgres", async ({ prisma }) => { + /* ... */ +}); +containerTest("should use both", async ({ prisma, redisOptions }) => { + /* ... */ +}); +``` + +## Code Style + +### Formatting and linting + +Format and lint are enforced by CI (`code-quality` check). Run before committing: + +```bash +pnpm run format # oxfmt — auto-fixes formatting +pnpm run lint:fix # oxlint — auto-fixes lint violations +pnpm run lint # oxlint — check only (no fixes) +``` + +### Imports + +**Prefer static imports over dynamic imports.** Only use dynamic `import()` when: +- Circular dependencies cannot be resolved otherwise +- Code splitting is genuinely needed for performance +- The module must be loaded conditionally at runtime + +Dynamic imports add unnecessary overhead in hot paths and make code harder to analyze. If you find yourself using `await import()`, ask if a regular `import` statement would work instead. + +## Changesets and Server Changes + +When modifying any public package (`packages/*` or `integrations/*`), add a changeset: + +```bash +pnpm run changeset:add +``` + +- Default to **patch** for bug fixes and minor changes +- Confirm with maintainers before selecting **minor** (new features) +- **Never** select major without explicit approval + +When modifying only server components (`apps/webapp/`, `apps/supervisor/`, etc.) with no package changes, add a `.server-changes/` file instead. See `.server-changes/README.md` for format and documentation. + +## Dependency Pinning + +Zod is pinned to a single version across the entire monorepo (currently `3.25.76`). When adding zod to a new or existing package, use the **exact same version** as the rest of the repo - never a different version or a range. Mismatched zod versions cause runtime type incompatibilities (e.g., schemas from one package can't be used as body validators in another). + +## Architecture Overview + +### Request Flow + +User API call -> Webapp routes -> Services -> RunEngine -> Redis Queue -> Supervisor -> Container execution -> Results back through RunEngine -> ClickHouse (analytics) + PostgreSQL (state) + +### Apps + +- **apps/webapp**: Remix 2.17.4 app - main API, dashboard, orchestration. Uses Express server. +- **apps/supervisor**: Manages task execution containers (Docker/Kubernetes). + +### Public Packages + +- **packages/trigger-sdk** (`@trigger.dev/sdk`): Main SDK for writing tasks +- **packages/cli-v3** (`trigger.dev`): CLI - also bundles code that goes into customer task images +- **packages/core** (`@trigger.dev/core`): Shared types. **Import subpaths only** (never root). +- **packages/build** (`@trigger.dev/build`): Build extensions and types +- **packages/react-hooks**: React hooks for realtime and triggering +- **packages/redis-worker** (`@trigger.dev/redis-worker`): Redis-based background job system + +### Internal Packages + +- **internal-packages/database**: Prisma 6.14.0 client and schema (PostgreSQL) +- **internal-packages/clickhouse**: ClickHouse client, schema migrations, analytics queries +- **internal-packages/run-engine**: "Run Engine 2.0" - core run lifecycle management +- **internal-packages/redis**: Redis client creation utilities (ioredis) +- **internal-packages/testcontainers**: Test helpers for Redis/PostgreSQL containers +- **internal-packages/schedule-engine**: Durable cron scheduling +- **internal-packages/zod-worker**: Graphile-worker wrapper (DEPRECATED - use redis-worker) + +### Legacy V1 Engine Code + +The `apps/webapp/app/v3/` directory name is misleading - most code there is actively used by V2. Only specific files are V1-only legacy (MarQS queue, triggerTaskV1, cancelTaskRunV1, etc.). See `apps/webapp/CLAUDE.md` for the exact list. When you encounter V1/V2 branching in services, only modify V2 code paths. All new work uses Run Engine 2.0 (`@internal/run-engine`) and redis-worker. + +### Documentation + +Docs live in `docs/` as a Mintlify site (MDX format). See `docs/CLAUDE.md` for conventions. + +### Reference Projects + +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 + +When updating Docker image references: + +- **Always use multiplatform/index digests**, not architecture-specific digests +- Architecture-specific digests cause CI failures on different build environments +- Use the digest from the main Docker Hub page, not from a specific OS/ARCH variant + +## Writing Trigger.dev Tasks + +Always import from `@trigger.dev/sdk`. Never use `@trigger.dev/sdk/v3` or deprecated `client.defineJob`. + +```typescript +import { task } from "@trigger.dev/sdk"; + +export const myTask = task({ + id: "my-task", + run: async (payload: { message: string }) => { + // Task logic + }, +}); +``` + +### SDK Documentation Rules + +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 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 (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 (from your `references` clone): `cd projects/hello-world && pnpm exec trigger dev` + +## Local Task Testing Workflow + +### Step 1: Start Webapp in Background + +```bash +# Run from repo root with run_in_background: true +pnpm run dev --filter webapp +curl -s http://localhost:3030/healthcheck # Verify running +``` + +### Step 2: Start Trigger Dev in Background + +```bash +# in your triggerdotdev/references clone +cd projects/hello-world && pnpm exec trigger dev +# Wait for "Local worker ready [node]" +``` + +### Step 3: Trigger and Monitor Tasks via MCP + +``` +mcp__trigger__get_current_worker(projectRef: "proj_rrkpdguyagvsoktglnod", environment: "dev") +mcp__trigger__trigger_task(projectRef: "proj_rrkpdguyagvsoktglnod", environment: "dev", taskId: "hello-world", payload: {"message": "Hello"}) +mcp__trigger__list_runs(projectRef: "proj_rrkpdguyagvsoktglnod", environment: "dev", taskIdentifier: "hello-world", limit: 5) +``` + +Dashboard: http://localhost:3030/orgs/references-9dfd/projects/hello-world-97DT/env/dev/runs + + + +# Skill mappings — when working in these areas, load the linked skill file into context. + +skills: + +- task: "Using agentcrumbs for debug tracing, adding crumbs, trails, markers, querying traces, or stripping debug code before merge" + load: "node_modules/agentcrumbs/skills/agentcrumbs/SKILL.md" +- task: "Setting up agentcrumbs in the project, initializing namespace catalog, running crumbs init" + load: "node_modules/agentcrumbs/skills/agentcrumbs/init/SKILL.md" + + +## agentcrumbs + +Add crumbs as you write code — not just when debugging. Mark lines with +`// @crumbs` or wrap blocks in `// #region @crumbs`. They stay on the +branch throughout development and are stripped by `agentcrumbs strip` +before merge. + +### Namespaces + +| Namespace | Description | Path | +| ----------------- | ---------------------------------------------- | ----------------------------------- | +| `webapp` | Main Remix app — API, dashboard, orchestration | `apps/webapp` | +| `supervisor` | Task execution container manager | `apps/supervisor` | +| `sdk` | Main SDK for writing tasks | `packages/trigger-sdk` | +| `cli` | CLI and task image bundling | `packages/cli-v3` | +| `core` | Shared types and subpath exports | `packages/core` | +| `build` | Build extensions and types | `packages/build` | +| `react-hooks` | React hooks for realtime/triggering | `packages/react-hooks` | +| `redis-worker` | Redis-based background job system | `packages/redis-worker` | +| `run-engine` | Run Engine 2.0 — core run lifecycle | `internal-packages/run-engine` | +| `database` | Prisma client and schema | `internal-packages/database` | +| `clickhouse` | ClickHouse client, migrations, analytics | `internal-packages/clickhouse` | +| `schedule-engine` | Durable cron scheduling | `internal-packages/schedule-engine` | +| `run-queue` | Run queue management | `internal-packages/run-queue` | + +Do not invent new namespaces — pick from this table or ask first. + +### For PR reviewers + +Do not flag `// @crumbs` markers, `#region @crumbs` blocks, or agentcrumbs +imports in reviews. These are temporary debug instrumentation stripped +before merge. Data logged in crumbs (IDs, names, values) never reaches +production. + +### CLI + +```bash +pnpm exec agentcrumbs collect # start collector (multi-service) +pnpm exec agentcrumbs tail --app trigger # live tail +pnpm exec agentcrumbs clear --app trigger # remove crumbs before merge +``` + +The preferred way to query for crumbs is to use `pnpm exec agentcrumbs query --app trigger` with the `--limit` option and cursor pagination, and clear existing crumbs before reproducing a bug via `pnpm exec agentcrumbs clear --app trigger`. diff --git a/CLAUDE.md b/CLAUDE.md index 476c1edd8d..43c994c2d3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,274 +1 @@ -# CLAUDE.md - -This file provides guidance to Claude Code when working with this repository. Subdirectory CLAUDE.md files provide deeper context when you navigate into specific areas. - -## Build and Development Commands - -This is a pnpm 10.33.2 monorepo using Turborepo. Run commands from root with `pnpm run`. - -**Adding dependencies:** Edit `package.json` directly instead of using `pnpm add`, then run `pnpm i` from the repo root. See `.claude/rules/package-installation.md` for the full process. - -```bash -pnpm run docker # Core dev services (Postgres, Redis, Electric, MinIO, ClickHouse, s2-lite) -# pnpm run docker:full # Same + observability stack (Prometheus, Grafana, OTEL) and chaos tooling -pnpm run db:migrate # Run database migrations -pnpm run db:seed # Seed the database (required for reference projects) - -# Build packages (required before running) -pnpm run build --filter webapp && pnpm run build --filter trigger.dev && pnpm run build --filter @trigger.dev/sdk - -pnpm run dev --filter webapp # Run webapp (http://localhost:3030) -pnpm run dev --filter trigger.dev --filter "@trigger.dev/*" # Watch CLI and packages -``` - -### Verifying Changes - -The verification command depends on where the change lives: - -- **Apps and internal packages** (`apps/*`, `internal-packages/*`): Use `typecheck`. **Never use `build`** for these — building proves almost nothing about correctness. -- **Public packages** (`packages/*`): Use `build`. - -```bash -# Apps and internal packages — use typecheck -pnpm run typecheck --filter webapp # ~1-2 minutes -pnpm run typecheck --filter @internal/run-engine - -# Public packages — use build -pnpm run build --filter @trigger.dev/sdk -pnpm run build --filter @trigger.dev/core -``` - -Only run typecheck/build after major changes (new files, significant refactors, schema changes). For small edits, trust the types and let CI catch issues. - -## Testing - -We use vitest exclusively. **Never mock anything** - use testcontainers instead. - -```bash -pnpm run test --filter webapp # All tests for a package -cd internal-packages/run-engine -pnpm run test ./src/engine/tests/ttl.test.ts --run # Single test file -pnpm run build --filter @internal/run-engine # May need to build deps first -``` - -Test files go next to source files (e.g., `MyService.ts` -> `MyService.test.ts`). - -### Testcontainers for Redis/PostgreSQL - -```typescript -import { redisTest, postgresTest, containerTest } from "@internal/testcontainers"; - -redisTest("should use redis", async ({ redisOptions }) => { - /* ... */ -}); -postgresTest("should use postgres", async ({ prisma }) => { - /* ... */ -}); -containerTest("should use both", async ({ prisma, redisOptions }) => { - /* ... */ -}); -``` - -## Code Style - -### Formatting and linting - -Format and lint are enforced by CI (`code-quality` check). Run before committing: - -```bash -pnpm run format # oxfmt — auto-fixes formatting -pnpm run lint:fix # oxlint — auto-fixes lint violations -pnpm run lint # oxlint — check only (no fixes) -``` - -### Imports - -**Prefer static imports over dynamic imports.** Only use dynamic `import()` when: -- Circular dependencies cannot be resolved otherwise -- Code splitting is genuinely needed for performance -- The module must be loaded conditionally at runtime - -Dynamic imports add unnecessary overhead in hot paths and make code harder to analyze. If you find yourself using `await import()`, ask if a regular `import` statement would work instead. - -## Changesets and Server Changes - -When modifying any public package (`packages/*` or `integrations/*`), add a changeset: - -```bash -pnpm run changeset:add -``` - -- Default to **patch** for bug fixes and minor changes -- Confirm with maintainers before selecting **minor** (new features) -- **Never** select major without explicit approval - -When modifying only server components (`apps/webapp/`, `apps/supervisor/`, etc.) with no package changes, add a `.server-changes/` file instead. See `.server-changes/README.md` for format and documentation. - -## Dependency Pinning - -Zod is pinned to a single version across the entire monorepo (currently `3.25.76`). When adding zod to a new or existing package, use the **exact same version** as the rest of the repo - never a different version or a range. Mismatched zod versions cause runtime type incompatibilities (e.g., schemas from one package can't be used as body validators in another). - -## Architecture Overview - -### Request Flow - -User API call -> Webapp routes -> Services -> RunEngine -> Redis Queue -> Supervisor -> Container execution -> Results back through RunEngine -> ClickHouse (analytics) + PostgreSQL (state) - -### Apps - -- **apps/webapp**: Remix 2.17.4 app - main API, dashboard, orchestration. Uses Express server. -- **apps/supervisor**: Manages task execution containers (Docker/Kubernetes). - -### Public Packages - -- **packages/trigger-sdk** (`@trigger.dev/sdk`): Main SDK for writing tasks -- **packages/cli-v3** (`trigger.dev`): CLI - also bundles code that goes into customer task images -- **packages/core** (`@trigger.dev/core`): Shared types. **Import subpaths only** (never root). -- **packages/build** (`@trigger.dev/build`): Build extensions and types -- **packages/react-hooks**: React hooks for realtime and triggering -- **packages/redis-worker** (`@trigger.dev/redis-worker`): Redis-based background job system - -### Internal Packages - -- **internal-packages/database**: Prisma 6.14.0 client and schema (PostgreSQL) -- **internal-packages/clickhouse**: ClickHouse client, schema migrations, analytics queries -- **internal-packages/run-engine**: "Run Engine 2.0" - core run lifecycle management -- **internal-packages/redis**: Redis client creation utilities (ioredis) -- **internal-packages/testcontainers**: Test helpers for Redis/PostgreSQL containers -- **internal-packages/schedule-engine**: Durable cron scheduling -- **internal-packages/zodworker**: Graphile-worker wrapper (DEPRECATED - use redis-worker) - -### Legacy V1 Engine Code - -The `apps/webapp/app/v3/` directory name is misleading - most code there is actively used by V2. Only specific files are V1-only legacy (MarQS queue, triggerTaskV1, cancelTaskRunV1, etc.). See `apps/webapp/CLAUDE.md` for the exact list. When you encounter V1/V2 branching in services, only modify V2 code paths. All new work uses Run Engine 2.0 (`@internal/run-engine`) and redis-worker. - -### Documentation - -Docs live in `docs/` as a Mintlify site (MDX format). See `docs/CLAUDE.md` for conventions. - -### Reference Projects - -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 - -When updating Docker image references: - -- **Always use multiplatform/index digests**, not architecture-specific digests -- Architecture-specific digests cause CI failures on different build environments -- Use the digest from the main Docker Hub page, not from a specific OS/ARCH variant - -## Writing Trigger.dev Tasks - -Always import from `@trigger.dev/sdk`. Never use `@trigger.dev/sdk/v3` or deprecated `client.defineJob`. - -```typescript -import { task } from "@trigger.dev/sdk"; - -export const myTask = task({ - id: "my-task", - run: async (payload: { message: string }) => { - // Task logic - }, -}); -``` - -### SDK Documentation Rules - -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 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 (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 (from your `references` clone): `cd projects/hello-world && pnpm exec trigger dev` - -## Local Task Testing Workflow - -### Step 1: Start Webapp in Background - -```bash -# Run from repo root with run_in_background: true -pnpm run dev --filter webapp -curl -s http://localhost:3030/healthcheck # Verify running -``` - -### Step 2: Start Trigger Dev in Background - -```bash -# in your triggerdotdev/references clone -cd projects/hello-world && pnpm exec trigger dev -# Wait for "Local worker ready [node]" -``` - -### Step 3: Trigger and Monitor Tasks via MCP - -``` -mcp__trigger__get_current_worker(projectRef: "proj_rrkpdguyagvsoktglnod", environment: "dev") -mcp__trigger__trigger_task(projectRef: "proj_rrkpdguyagvsoktglnod", environment: "dev", taskId: "hello-world", payload: {"message": "Hello"}) -mcp__trigger__list_runs(projectRef: "proj_rrkpdguyagvsoktglnod", environment: "dev", taskIdentifier: "hello-world", limit: 5) -``` - -Dashboard: http://localhost:3030/orgs/references-9dfd/projects/hello-world-97DT/env/dev/runs - - - -# Skill mappings — when working in these areas, load the linked skill file into context. - -skills: - -- task: "Using agentcrumbs for debug tracing, adding crumbs, trails, markers, querying traces, or stripping debug code before merge" - load: "node_modules/agentcrumbs/skills/agentcrumbs/SKILL.md" -- task: "Setting up agentcrumbs in the project, initializing namespace catalog, running crumbs init" -load: "node_modules/agentcrumbs/skills/agentcrumbs/init/SKILL.md" - - -## agentcrumbs - -Add crumbs as you write code — not just when debugging. Mark lines with -`// @crumbs` or wrap blocks in `// #region @crumbs`. They stay on the -branch throughout development and are stripped by `agentcrumbs strip` -before merge. - -### Namespaces - -| Namespace | Description | Path | -| ----------------- | ---------------------------------------------- | ----------------------------------- | -| `webapp` | Main Remix app — API, dashboard, orchestration | `apps/webapp` | -| `supervisor` | Task execution container manager | `apps/supervisor` | -| `sdk` | Main SDK for writing tasks | `packages/trigger-sdk` | -| `cli` | CLI and task image bundling | `packages/cli-v3` | -| `core` | Shared types and subpath exports | `packages/core` | -| `build` | Build extensions and types | `packages/build` | -| `react-hooks` | React hooks for realtime/triggering | `packages/react-hooks` | -| `redis-worker` | Redis-based background job system | `packages/redis-worker` | -| `run-engine` | Run Engine 2.0 — core run lifecycle | `internal-packages/run-engine` | -| `database` | Prisma client and schema | `internal-packages/database` | -| `clickhouse` | ClickHouse client, migrations, analytics | `internal-packages/clickhouse` | -| `schedule-engine` | Durable cron scheduling | `internal-packages/schedule-engine` | -| `run-queue` | Run queue management | `internal-packages/run-queue` | - -Do not invent new namespaces — pick from this table or ask first. - -### For PR reviewers - -Do not flag `// @crumbs` markers, `#region @crumbs` blocks, or agentcrumbs -imports in reviews. These are temporary debug instrumentation stripped -before merge. Data logged in crumbs (IDs, names, values) never reaches -production. - -### CLI - -```bash -pnpm exec agentcrumbs collect # start collector (multi-service) -pnpm exec agentcrumbs tail --app trigger # live tail -pnpm exec agentcrumbs clear --app trigger # remove crumbs before merge -``` - -The preferred way to query for crumbs is to use `pnpm exec agentcrumbs query --app trigger` with the `--limit` option and cursor pagination, and clear existing crumbs before reproducing a bug via `pnpm exec agentcrumbs clear --app trigger`. +@AGENTS.md