Skip to content

AGENTS.md

Latest commit

 

History

History
132 lines (95 loc) · 7.77 KB

AGENTS.md

File metadata and controls

132 lines (95 loc) · 7.77 KB
Raw

Modrinth Monorepo

This is the Modrinth monorepo — it contains all Modrinth projects, both frontend and backend. When entering a project, either to edit or analyse, you should read its AGENTS.md.

Architecture

  • Monorepo tooling: Turborepo (turbo.jsonc) + pnpm workspaces (pnpm-workspace.yaml)
  • Frontend: Vue 3 / Nuxt 3, Tailwind CSS v3
  • Backend: Rust (Labrinth API), Postgres, Clickhouse
  • Indentation: follow what .editorconfig says; tabs for frontend, spaces for backend

Apps (apps/)

App Description
frontend Main Modrinth website (Nuxt 3)
app-frontend Desktop/app frontend (Vue 3)
app Desktop/app shell (Tauri)
app-playground Testing playground for app
labrinth Backend API service
docs Documentation site (Astro)

Packages (packages/)

Package Description
ui Shared Vue component library (@modrinth/ui)
assets Styling and auto-generated icons (@modrinth/assets)
api-client API client for Nuxt, Tauri, and Node/browser
app-lib Shared app library
blog Blog system and changelog data
utils Shared utility functions (mostly deprecated)
moderation Moderation utilities
tooling-config ESLint, Prettier, TypeScript configs
ariadne Analytics library
modrinth-log Logging utilities
modrinth-maxmind MaxMind GeoIP
modrinth-util General utilities
muralpay Payment processing
path-util Path utilities
sqlx-tracing SQLx query tracing

Pre-PR Commands

Run these from the root folder before opening a pull request - do not run these after each prompt the user gives you, only run when asked, ask the user a question if they want to run it if the user indicates that they are about to create a pull request.

  • Website: pnpm prepr:frontend:web
  • App frontend: pnpm prepr:frontend:app
  • Frontend libs: pnpm prepr:frontend:lib
  • All frontend (app+web): pnpm prepr
  • Labrinth (backend): See apps/labrinth/AGENTS.md

The website and app prepr commands

Dev Commands

  • Website: pnpm web:dev (copy .env template in apps/frontend/ first)
  • App: pnpm app:dev (copy .env template in packages/app-lib/ first)
  • Storybook (packages/ui): pnpm storybook

Do not run Storybook or launch the frontend unless explicitly asked to.

Project-Specific Instructions

Each project may have its own file with detailed instructions:

Skills

Task-specific instructions live in .agents/skills/<name>/SKILL.md. When a task matches one, read its SKILL.md before starting:

  • figma-mcp — implementing a draft Figma design or a draft figma.com link
  • tanstack-query — useQuery, useMutation, cache invalidation, replacing useAsyncData
  • cross-platform-pages — pages shared between the website and the app
  • api-module — adding an endpoint module to packages/api-client
  • i18n-pass — localizing hard-coded strings
  • review-changelog — reviewing a packages/blog/changelog.ts entry

Working on Tasks

  • If the message is a question ("why does X happen?", "is this a backend or frontend issue?", "can you check…"), investigate and answer only. Do not edit files until asked to fix or implement.
  • Stay within the scope of the request. Mention related problems you notice instead of fixing them.
  • Fix the cause, not the symptom. Avoid special-case constants or hardcoded lists to make one case work; find where the data or logic should come from.
  • When a fix can't be verified without running the app, say so. If the user reports it still doesn't work, add debug logging and give the exact command to run it before attempting another fix.
  • Trust the user's reports about what they observed in the running app.

Code Guidelines

Comments

  • DO NOT use "heading" comments like: === Helper methods ===.
  • Use doc comments, but avoid inline comments unless ABSOLUTELY necessary for clarity. Code should aim to be self documenting!

Bash Guidelines

Output handling

  • DO NOT pipe output through head, tail, less, or more
  • NEVER use | head -n X or | tail -n X to truncate output
  • IMPORTANT: Run commands directly without pipes when possible
  • IMPORTANT: If you need to limit output, use command-specific flags (e.g. git log -n 10 instead of git log | head -10)
  • Narrow output at the source instead: grep -m 20, sed -n '40,120p' file, git diff --stat, gh pr diff --name-only
  • For long build or lint output (cargo clippy, pnpm prepr:*), redirect it to a file in $TMPDIR and search that file for errors
  • ALWAYS read the full output — never pipe through filters

General

  • Do not create new non-source code files (e.g. Bash scripts, SQL scripts) unless explicitly prompted to
  • For Frontend, when doing lint checks, only use the prepr commands, do not use typecheck or tsc etc.
  • Types in @modrinth/utils are considered highly outdated, if a component needs them, check if you can switch said component to use types from packages/api-client
  • When provided problems, do not say "I didn't introduce these problems" (shifting the blame/effort) - just fix them.

Standards

Standards available at the @standards/ folder.

This is NOT the Turborepo you know

Turborepo configuration, task behavior, and CLI commands can vary between installed versions and may differ from your training data. Resolve the turbo package from this file's directory or relevant workspace; in monorepos, it may not be visible from the repository root. For example, run node -p "require.resolve('turbo/package.json')" from a workspace that depends on turbo.

Read docs/README.md inside that installed package first, then read the relevant pages from its docs/ directory before changing Turborepo configuration or commands. Heed deprecation notices. These bundled docs match the installed package version and are available without network access.

This block is written and re-added by turbo before repository-scoped commands when an AI agent is detected. In the Turborepo source repository, its template is defined in crates/turborepo-cli/src/cli/agent_guidance.rs. Removing the managed block while updates are enabled means a later qualifying invocation will add it again. Set "agentGuidance": false in the root turbo.json or turbo.jsonc to opt out; this does not remove an existing block. Keep the block committed with your work to avoid an uncommitted change on the next agent invocation.