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.

Execution Mode

Direct Implementation Mode is the default. Large task size alone is not enough to trigger RFC, ADR, slicing, phase planning, or proceed gates.

Use docs/development/ai/protocols/ai-execution-protocol.md for the current mode definitions. Use docs/development/ai/protocols/cost-gate.md as a risk hint, not as an automatic blocker. Enter Opt-in Slicing Mode only when the user explicitly requests it, or when a high-risk task truly needs confirmation before safe implementation.

Documentation Style

AI-written docs should use table-first Markdown for comparable facts.

Content shape	Preferred format	Notes
Route maps, package maps, app registries, command inventories, ownership boundaries, or lifecycle states	Table with explicit columns	Add columns such as `Owner`, `Route`, `Status`, `Boundary`, `Runtime`, `Check`, or `Notes` when they help readers compare rows.
A sequence of repeated subsections that each contain a short list	Summary table first, detailed subsections second	The table gives humans and agents a complete map before the narrative expands.
Ordered workflows or required command sequences	Ordered list or checklist	Keep sequence visible when order matters.
Strategic thesis or rationale	Prose, with a small table only when tradeoffs need comparison	Do not turn every paragraph into a matrix.

Operating Principles

Principle	Why it matters
Prefer small, reviewable diffs.	Maintainers can verify AI work without rereading unrelated domains.
Read only the domain documents needed for the task.	Context stays relevant and costs stay bounded.
Preserve package boundaries before optimizing implementation details.	The monorepo stays navigable as apps and runtimes grow.
Explain package boundary impact when a task touches multiple apps or packages.	Reviewers can see whether architecture docs or dependency rules changed.
Do not assume architecture decisions that are not documented.	AI agents should not invent hidden policy.
Do not introduce unnecessary dependencies.	Runtime and bundle size stay under control.

Safety Summary

Rule	Boundary
Do not commit secrets or real `.env` values.	Secrets stay outside git.
Do not change production database configuration.	Production data remains human-controlled.
Do not run destructive database operations.	Destructive work requires explicit approval.
Production writes, migrations, and infrastructure changes require explicit human approval.	High-risk changes are proceed-gated.
Browser apps must not execute local commands or import `child_process`.	Shell execution requires a separate approved runtime boundary.

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.

Recommended Commit Message

When an AI coding session changes repository files, the final response must include a recommended git commit message. The message should be copy-ready, descriptive, and preferably follow Conventional Commits. For multi-area changes, include a concise bullet body that names the main product areas changed and the validation that was run. The AI must not claim that it committed unless the maintainer explicitly asked it to commit.

Where To Look

Need	Document
Read routing	`docs/start-here/context-pack.md`
Package boundaries	`docs/platform/architecture/repo/package-graph.md`
App registry	`docs/platform/architecture/apps/app-registry.md`
Window system	`docs/platform/architecture/shell/window-manager.md`
State ownership	`docs/platform/architecture/data/state-model.md`
API direction	`docs/platform/architecture/data/api-map.md`
Refactor guardrails	`docs/platform/architecture/repo/refactor-guardrails.md`