Agent Rules

AGENTS.md is the authoritative rulebook for AI coding agents in this repository.

Purpose

AGENTS.md is the authoritative rulebook for AI coding agents in this repository.

This document is a short companion for humans and agents who want the operating philosophy without rereading every strong rule.

Committed code, comments, mock data, app copy, and docs (except i18n assets under apps/os-shell/src/i18n/**) should be English. See AGENTS.md → Repository Language (English, Except i18n). Chat with AI tools may be in any language; deliverables in the repo should still follow this rule. Do not write Chinese/CJK placeholders into source files or AI-facing docs; use English placeholders and run pnpm check:cjk when touching text-heavy artifacts.

Cost Gate

Large tasks must use S / M / L / XL classification and execution modes in docs/ai/ai-execution-protocol.md before coding. AGENTS.md is authoritative.

Operating Principles

Prefer small, reviewable diffs.
Read only the domain documents needed for the task.
Preserve package boundaries before optimizing implementation details.
Explain package boundary impact when a task touches multiple apps or packages.
Do not assume architecture decisions that are not documented.
Do not introduce unnecessary dependencies.

Safety Summary

Do not commit secrets or real .env values.
Do not change production database configuration.
Do not run destructive database operations.
Production writes, migrations, and infrastructure changes require explicit human approval.
Browser apps must not execute local commands or import child_process.

Verification Summary

For non-trivial code changes, the standard checks are:

pnpm lint
pnpm typecheck
pnpm arch:check
pnpm check:cjk

For structural refactors or package moves, also run:

pnpm check:file-size

If a check is skipped or fails for a known pre-existing reason, report it clearly in the final response.

Where To Look

Read routing: docs/ai/context-pack.md
Package boundaries: docs/architecture/package-graph.md
App registry: docs/architecture/app-registry.md
Window system: docs/architecture/window-manager.md
State ownership: docs/architecture/state-model.md
API direction: docs/architecture/api-map.md
Refactor guardrails: docs/architecture/refactor-guardrails.md