Sentry Dart/Flutter SDK

Melos monorepo. Each package lives in packages/<name>/ with its own pubspec.yaml.

Packages

Environment

• Minimum supported: Flutter 3.44.0 | Dart 3.12.0 (enforced by min_version_test.yml and the 3.12 leg of dart.yml)
• The analyze gate runs on the latest stable Dart (currently 3.13), since setup-dart and .fvmrc are both unpinned — see the format footgun below
• package-analysis installs pana unpinned as well, so a new pana release can move scores below the 140 threshold on its own (0.23.18 stopped following the per-package CHANGELOG.md symlink, costing every package 5 points)
• Use fvm dart / fvm flutter if available (check with which fvm), else dart / flutter

Package Types

Check pubspec.yaml environment: section:

• Dart-only (no flutter: key): sentry, sentry_dio, sentry_file, sentry_logging
• Flutter (has flutter: key): sentry_flutter, sentry_sqflite, sentry_drift, etc.

File-Scoped Commands

Run from within the package directory (e.g., cd packages/dart/):

Format version footgun: CI's analyze gate (.github/workflows/analyze.yml) runs dart format --set-exit-if-changed ./ using the dart set up for that job's sdk input — setup-dart for dart packages, flutter-action's Flutter-bundled dart (stable channel) for flutter packages — not the package's environment: constraint. dart_style differs between Dart minor versions, so formatting with a local dart of a different version can leave the gate red. Neither source is pinned, so a new stable Dart release can turn the gate red without any code change — the two styles are mutually exclusive, so whichever version CI resolves is the one the repo must be formatted with. This has bitten packages/flutter (Flutter-bundled Dart 3.12 joined a line that system Dart 3.10 didn't) and packages/dart (Dart 3.13 collapses trailing named args after a function literal, e.g. test('...', () {...}, onPlatform: {...}), which 3.12 splits). Before pushing format changes, format with the dart CI uses for that package — the Flutter SDK's bundled bin/cache/dart-sdk/bin/dart for flutter packages, latest stable dart for dart packages (an fvm Flutter whose bundled dart matches works: ls ~/fvm/versions) — and verify with --output=none --set-exit-if-changed. A newer analyzer can also add fatal-warnings failures (e.g. unused_catch_stack on catch (e, _)), so run dart analyze with that same SDK. Note that .githooks/pre-commit formats staged .dart files with the fvm SDK (.fvm/flutter_sdk, falling back to the main worktree's copy, then bare dart on PATH) and fails the commit if anything changed, without re-staging — if the fvm Flutter's bundled dart differs from the one CI uses for that package, it will reformat to the wrong style, so review the diff rather than blindly git add-ing it.

Conventions

• Ask clarifying questions and/or propose a plan before implementation
• Write failing tests before implementation; fix regressions with a reproducing test first
• NEVER commit or push code unless explicitly asked
• NEVER edit CHANGELOG.md — entries are auto-generated by craft from the PR title. For a custom entry, add a ## Changelog Entry section to the PR description (not the file); apply the skip-changelog label to exclude. See CONTRIBUTING.md
• See CONTRIBUTING.md for setup and contribution workflow

Command Execution

• Verify working directory — use pwd to confirm you're in the correct path before running commands. The shell persists working directory across tool calls
• Avoid redundant cd — do not prefix every command with cd <path> &&. Change directory once if needed, then verify with pwd
• Wildcard permissions — many commands are pre-approved with wildcards (e.g., git add:*). Flags like -C change the command prefix (git -C path add ≠ git add), triggering a confirmation prompt. Avoid -C when you can change directory instead
• Prefer small, focused commands over one massive pipeline. Break complex operations into multiple steps
• JSON processing — always use jq; do not shell out to node or python for JSON parsing
• GitHub — prefer gh CLI over web scraping when interacting with GitHub.com

Commits

• Conventional Commits 1.0.0 — subject max 50 chars, body max 72 chars/line
• AI attribution — AI-generated commits must include a Co-Authored-By footer (e.g., Co-Authored-By: Claude <noreply@anthropic.com>)
• File renames — always use git mv, never mv + git add
• Commit types — see .github/release.yml for the list of types and how they map to changelog categories

Pull Requests

• Title — same format as commit subject where the beginning of subject must be capitalized for human-authored PRs (Conventional Commits): type(scope): Capitalized description (automated bot PRs may start lowercase)
• Branch naming — <type>/<short-description> (e.g., feat/session-replay-privacy, fix/memory-leak-scope)
• PR template — .github/pull_request_template.md includes: description, motivation, how tested, checklist
• Reviewers — assigned via CODEOWNERS (.github/CODEOWNERS); one maintainer approval is sufficient
• Changelog — never edit CHANGELOG.md; entries are auto-generated by craft from the PR title. Put a custom entry in the PR description's ## Changelog Entry section, or apply skip-changelog to exclude. See CONTRIBUTING.md
• Draft PRs — use for work-in-progress; convert to ready when seeking review

Context-Aware Loading

Use the right AGENTS.md for the area you're working in:

• Core SDK (packages/dart/) → packages/dart/AGENTS.md
• Flutter SDK (packages/flutter/) → packages/flutter/AGENTS.md
• General → This file for monorepo-wide commands and conventions

Skills

These form a workflow pipeline — each is model-invoked (the agent reaches for it on its triggers) and hands off to the next:

spec → design-first → code-guidelines + test-guidelines → diagnosing-bugs → review

• spec — Turn an issue link or a fuzzy ask into a verified spec (acceptance criteria) before design — the what
• design-first — Shape non-trivial work before writing it: modules, seams, public API surface — the how
• code-guidelines — Implement / refactor / review against the SDK's rules and constraints
• test-guidelines — Write or modify tests
• diagnosing-bugs — Hard bugs, flaky tests, CI hangs, performance regressions
• review — Three-axis branch review: Standards (our docs + public API surface), Spec (vs the spec above), Correctness (runtime bugs + SDK threat model)

With plan mode: plan mode enforces read-only + the approval gate; these skills supply the content. Plan with spec (the what) and design-first (the how) — their acceptance criteria + design sketch are the plan, and ExitPlanMode is the single sign-off (don't run a separate approval). code-guidelines is the constraint set the design must satisfy, not the driver. After approval, implement under code-guidelines / test-guidelines.

Maintaining Agent Docs

When you hit a wall that an instruction would have prevented, a documented command/path is wrong, or a convention has changed — propose an update to the relevant file:

• AGENTS.md — commands, environment, package structure, conventions
• .agents/skills/spec/SKILL.md — Turning an issue link or a fuzzy ask into a verified spec before design
• .agents/skills/design-first/SKILL.md — Shaping non-trivial work before writing it
• .agents/skills/code-guidelines/SKILL.md — Implementing features, refactoring, or reviewing code
• .agents/skills/test-guidelines/SKILL.md — Writing or modifying tests
• .agents/skills/diagnosing-bugs/SKILL.md — Hard bugs, flaky tests, CI hangs, performance regressions
• .agents/skills/review/SKILL.md — Three-axis branch review (Standards + Spec + Correctness)

Do NOT add task-specific fixes, things discoverable from code, or duplicates of what linters enforce. Always propose changes — do not silently edit these files.