# Remix Agent Guide

This repository includes the source code for Remix 3, a web framework for building modern web applications using TypeScript/JavaScript and web standard APIs.

## Repo Shape

- **Monorepo**: pnpm workspace with most product code under `packages/`
- **Public API layout**: every `exports` entry in `package.json` should map to a dedicated top-level `src/*.ts` file
- **Implementation layout**: `src/lib` is implementation-only; do not add barrel re-exports or thin pass-through wrappers inside `src/lib`
- **Cross-package boundaries**: do not re-export APIs or types from another package; import from the owning package directly
- **Platform stance**: prefer Web APIs and standards-aligned primitives over Node-specific APIs whenever possible

## Git Workflow

- **Worktrees**: do your work in a dedicated git worktree, not the main checkout. Don't nest worktrees inside the main checkout; they inherit its config files like `.oxlintrc.json`, which breaks `oxlint`
- **Main checkout**: leave the main Remix checkout on `main` and do not check out `main` in any other worktree; git only allows a branch to be checked out in one worktree at a time
- **Cleanup**: remove a worktree with `git worktree remove <path>` once its branch is merged or abandoned
- **Branch names**: use `<author>/<pr-description>`, where `author` is the GitHub username of the person making the commit and `pr-description` is a few meaningful, hyphen-separated words describing the pull request, for example `mjackson/fix-flaky-bun-test`

## Default Development Loop

- **Fast local loop**: `pnpm run validate-package-meta`, `pnpm run lint`, `pnpm run test:changed`, `pnpm run typecheck:changed`
- **Full CI-style validation**: `pnpm test` and `pnpm run typecheck`
- **When to use full runs locally**: broad cross-workspace changes, shared root config changes, release/publish flow changes, or anything that could affect the whole repo
- **Single package commands**: `pnpm --filter @remix-run/<package> run test --quiet`, `pnpm --filter @remix-run/<package> run typecheck`, `pnpm --filter @remix-run/<package> run build`
- **Single test file**: `cd packages/<package> && pnpm test --quiet src/**/<filename>.test.ts`
- **Scoped test names**: add `--only '<suite-or-test-regex>'` to focus tests by full suite/test name without editing source, for example `pnpm test --quiet --only 'loader redirects'`
- **Lint**: `pnpm run lint` or `pnpm run lint:fix`
- **Format**: `pnpm run format` or `pnpm run format:check`

The changed-workspace commands default to diffing against `origin/main` and include uncommitted working tree changes when `head-ref` is `HEAD`.

## Code Style

- **Imports**: use `import type { X }` and `export type { X }`; include `.ts` extensions
- **Variables**: use `let` for locals, `const` for module scope, never `var`
- **Functions**: use regular functions by default; use arrow functions for callbacks; use concise arrow bodies when they only return an expression
- **Object methods**: use shorthand method syntax
- **Classes**: omit TS accessibility modifiers; use native fields and `#private`
- **Generics**: use descriptive lowercase names like `source`, `pattern`, or `method`
- **Comments**: add non-JSDoc comments only when behavior is surprising or non-obvious
- **Formatting**: Oxfmt with `printWidth: 100`, no semicolons, single quotes, spaces not tabs

## Tests And Docs

- **Tests run from source**: no build step required
- **Test structure**: do not generate tests inside `describe()` with loops or conditionals; it breaks per-test IDE execution
- **Test guidance**: use the `write-tests` skill when adding, refactoring, or reviewing tests, fixtures, test scripts, or test-only dependencies
- **Docs and examples**: if you change a public API, update the related docs, JSDoc, README examples, and tests in the same change
- **README/install conventions**: use `npm i remix` in install snippets and import from `remix`, not `@remix-run/*`
- **README link conventions**: use full GitHub URLs for cross-file or cross-package repo links so copied docs render correctly; keep same-document anchors and README self-links relative

## GitHub

- **GitHub work**: when commenting on issues or pull requests, inspecting GitHub state, or otherwise working with GitHub, always use the `gh` command line tool when possible instead of an agent-specific connector
- **Agent attribution**: do not identify, credit, or attribute work to yourself or any other AI or agentic tool in commit messages, pull request titles or bodies, issue comments, release notes, or other GitHub-facing content. Do not add `Generated by`, `Co-authored-by`, tool branding, signatures, or similar agent-specific attribution. Present the work transparently in terms of the changes made and their rationale.

## Release Notes

- If a change affects published packages, add or update the appropriate change file.
- Package `.changes/` directories are optional. Create `packages/<package>/.changes/` on demand when adding a change file or prerelease config.
- Prerelease channels come from `packages/*/.changes/config.json` and control the version suffix such as `alpha` or `beta`; prerelease packages still publish to the npm `next` dist-tag.
- If you modify release or publish flow code, validate it with the preview or dry-run scripts before finishing.

## Repo Skills

For work on this repository itself, use the skills in `.agents/skills/`:

- `add-package` at `.agents/skills/add-package/SKILL.md`: Create or align a package under `packages/` with repo conventions.
- `author-ui-primitives` at `.agents/skills/author-ui-primitives/SKILL.md`: Build idiomatic headless primitives under `packages/ui`, including accessibility behavior and required structural styles.
- `fix-issue` at `.agents/skills/fix-issue/SKILL.md`: Fix bugs reported in GitHub issues.
- `make-changes` at `.agents/skills/make-changes/SKILL.md`: Create or update package change files under `packages/*/.changes`.
- `make-decision-doc` at `.agents/skills/make-decision-doc/SKILL.md`: Add a numbered decision document under `decisions/` capturing a non-obvious architectural choice.
- `make-demo` at `.agents/skills/make-demo/SKILL.md`: Create or revise demos in this repository with production-quality Remix patterns.
- `make-pr` at `.agents/skills/make-pr/SKILL.md`: Prepare and open clear, reviewer-friendly pull requests.
- `make-tracking-issue` at `.agents/skills/make-tracking-issue/SKILL.md`: Create or revise focused GitHub tracking issues with implementor context, a concise work plan, and required gates.
- `publish-placeholder-package` at `.agents/skills/publish-placeholder-package/SKILL.md`: Publish a `0.0.0` placeholder package to reserve an npm name.
- `review-pr` at `.agents/skills/review-pr/SKILL.md`: Review Remix pull requests from a local checkout.
- `remix` at `.agents/skills/remix/SKILL.md`: Build, review, and refactor Remix apps end to end, including project layout, routes, controllers, middleware, validation, data access, auth, sessions, uploads, UI, hydration, navigation, animations, and tests.
- `supersede-pr` at `.agents/skills/supersede-pr/SKILL.md`: Replace one pull request with another and close the superseded PR safely.
- `typescript-expert` at `.agents/skills/typescript-expert/SKILL.md`: Write, refactor, or review TypeScript with strict, precise, maintainable types.
- `update-pr` at `.agents/skills/update-pr/SKILL.md`: Rewrite an existing pull request title and body to match the current diff.
- `write-api-docs` at `.agents/skills/write-api-docs/SKILL.md`: Write or tighten JSDoc for exported public APIs.
- `write-readme` at `.agents/skills/write-readme/SKILL.md`: Draft or revise package READMEs in the repo's style.
- `write-tests` at `.agents/skills/write-tests/SKILL.md`: Write, refactor, or review tests with repo runner, fixture, assertion, dependency, and validation conventions.
- `write-ui-module-readme` at `.agents/skills/write-ui-module-readme/SKILL.md`: Write concise module README files for `packages/ui/src/lib/*` primitives.
- `write-ui-examples` at `.agents/skills/write-ui-examples/SKILL.md`: Design, document and review focused UI library examples, including an adversarial product UX review.

## App And Demo Skills

For working on Remix code in demos or writing Remix app code, use the root `remix` skill listed above.

The CLI prepack step copies `.agents/skills/remix` into the default app template so scaffolded apps can refer to `./.agents/skills/remix/SKILL.md`.