turborepo AGENTS.md

AGENTS.md

Instructions for AI agents working on this repository.

Architecture

See ARCHITECTURE.md for an overview of the turbo run command architecture.

Keeping Documentation Up to Date

When making changes to the codebase, check if the following docs need updates:

• ARCHITECTURE.md - Update when changing core turbo run components:

  • Run builder, package graph, task graph/engine
  • Task visitor, caching system, task hashing
  • Run tracking and summary generation
  • Any files in crates/turborepo-lib/src/run/, crates/turborepo-lib/src/engine/, crates/turborepo-lib/src/task_graph/, or crates/turborepo-cache/

• CONTRIBUTING.md - Update when changing:

  • Build process or development setup
  • Testing procedures or requirements
  • Project structure or tooling

• This file (AGENTS.md) - Update when changing:

  • PR requirements or CI workflows
  • Repository conventions or policies

Pull Request Guidelines

Always run pre-commit/pre-push hooks

• You are not allowed to use --no-verify when making a commit or push.
• If you do not have dependencies available, you can download them with pnpm install --frozen-lockfile.

Rust panic extraction policy

• Workspace Clippy lints deny .unwrap(), .unwrap_err(), .unwrap_none(), and .expect() in Rust targets covered by cargo lint.
• Crates with existing implementation-code violations may temporarily allow clippy::unwrap_used and clippy::expect_used at the crate root; remove those allows as each crate is cleaned up.
• Tests are exempt from this panic-extraction policy, but still linted by cargo lint with panic-extraction lints allowed under cfg(test).

CI task scheduling

• Test and lint workflows do not pre-classify changed paths. PR jobs run consistently and use the Turborepo task graph and cache where applicable.
• Same-repository PRs authenticate to Remote Cache through OIDC; fork PRs remain local-only.
• Rust CI restores full Cargo target state on Ubuntu, macOS, and Windows from trusted main snapshots; only main writes. Repository sccache dogfooding is disabled.
• Linux Rust shards include terminal-control black-box TUI integration tests; known regressions remain explicitly ignored.
• Rust test shards pin Node.js 18.20.2, so any packageManager version an integration fixture declares has to run on that Node.
• Rust test shards and the @turbo/repository native-package matrix install the pinned uv version because Python workspace discovery invokes uv workspace metadata.
• Rust integration tests read fixtures from turborepo-tests/integration/fixtures/, never from examples/. Examples are version-bumped on their own cadence and are not declared inputs of the Rust test task.
• Example validation remains push-only because it requires Vercel credentials and project state.