# AGENTS.md **Planet agent harness. Defines behavior for coding agents working in this repository.** --- ## Harness Compatibility This file is the single authoritative agent guide for the Planet repository. The older lowercase `agents.md` entry has been merged here so coding agents and harness tools use one source of truth. ### Source Of Truth - `rules.md` is the mandatory repository rule source. Always load `core`, `security`, and `workflow`; load only task-relevant modules after that. - `AGENTS.md` defines the local agent operating mode and evidence gates. - `project_context.md` is background, not a rule source. Prefer newer implementation docs when it disagrees with current code. - `.codex/skills/` is the active specialized workflow layer for cleanup, docs, goal-driven work, and release. - Do not duplicate long workflow text across harness files. Durable constraints belong in `rules.md`; task procedures belong in skills or scripts. Read these files before changing code: 1. `rules.md` 2. `AGENTS.md` 3. `project_context.md` 4. `README.md` 5. `docs/HARNESS.md` 6. `CODEMAP.md` For documentation work, also read `docs/documentation-coverage-rules.md`. ### Start Safely Before broad edits: ```bash git status --short scripts/harness/doctor.sh ``` Use focused context commands before reading large files: ```bash rg -n "" git diff --stat HEAD git diff --name-only HEAD git diff --unified=0 HEAD -- ``` Preserve user changes already present in the worktree. ### Validation Fast local harness validation: ```bash scripts/harness/quick-check.sh ``` Full local validation: ```bash scripts/harness/validate.sh ``` `validate.sh` includes quick checks, frontend Bun build, and frontend smoke unless disabled by its documented environment flags. Docker image smoke builds are intentionally opt-in: ```bash PLANET_HARNESS_DOCKER_SMOKE=1 scripts/harness/validate.sh ``` Harness scripts resolve `bun`, `uv`, and optional delivery tools from the current non-interactive environment first. If a tool is missing there, they ask the user's login interactive shell instead of assuming a specific dotfile. ### High-Risk Areas - `planet.sh` owns local lifecycle, ports, WSL/LAN behavior, and destructive `destroy` cleanup. - Frontend package management is Bun-only. Do not use npm, pnpm, or yarn. - Frontend changes must satisfy `scripts/harness/frontend-rules-check.sh`; use rendered smoke evidence for public pages, auth guards, authenticated admin route/section availability, safe navigation/search/tab interactions, mobile layout, and 125% / 150% zoom, not only a build. - Admin or Docs layout changes must load `rules.md` `uiux` and preserve the one-screen (`一屏` / `首屏`) height chain: route roots use `height: 100%`, intermediate wrappers keep `min-height: 0`, and only the intended child owns scrolling. - `aiprovider` is a protocol/provider adapter; keep business prompts and product workflows in the backend. - Earth rendering depends on layer order, depth behavior, picking, and performance-sensitive Three.js code. - Secrets belong in environment files or configured settings stores, never in committed files. - Backend service code must use structured logging instead of `print()` or debugger calls; `scripts/harness/backend-rules-check.sh` enforces this. ### Conflict Policy Existing project rules and workflows win. If new harness guidance conflicts with `rules.md`, `AGENTS.md`, current docs, scripts, or CI, keep the existing behavior and document the compatibility note in `docs/harness-audit.md` or `docs/HARNESS.md`. --- ## Operating Mode - Default to acting directly when the user gives a clear task. - Ask before acting only when the missing decision is risky, cannot be discovered from repository context, and no conservative assumption is safe. - Read relevant files before editing. - Prefer focused CLI evidence: `rg`, `git diff --stat`, `git diff --name-only`, focused file reads, tests, builds, linters, and harness scripts. - Keep changes scoped to the requested area. Do not mix cleanup, feature work, release work, and documentation unless the task requires it. --- ## Evidence Gates - Visual inputs are blocking evidence. If the user provides a screenshot, image, mock, browser capture, or visual reference, obtain evidence from the artifact before interpreting intent or editing code. - Path resolution is part of the task. If the path cannot be opened, first try reasonable local equivalents such as WSL/Windows path conversion, workspace-relative lookup, absolute paths, and attached-file locations. - Never guess from prompt text, filenames, previous context, logs, OCR, or memory when a visual artifact was provided but cannot be accessed. - OCR is acceptable evidence for text-only visual questions or non-multimodal environments; state that OCR was used as the fallback. Layout, color, spacing, pixel, and rendering issues need real visual inspection or a clear limitation note. - If a visual artifact still cannot be inspected, say so and pause that visual-dependent part of the work. - Claims of completion need evidence: a relevant test, build, lint, screenshot, diff, direct file check, or harness result. - For UI and rendering changes, verify the rendered result when local tooling allows it. --- ## Communication - Match the user's language. Use Chinese for Chinese requests unless the user asks otherwise. - Keep updates short and specific: what is being inspected, edited, or verified. - Final responses should summarize changed files and verification, with blockers stated plainly. - Use file references with line numbers when explaining code or review findings. --- ## Quality Bar - Prefer existing project patterns over new abstractions. - Remove stale branches, mocks, compatibility paths, and duplicated helpers once a stable path exists. - Centralize prompts, constants, defaults, and shared request/response handling. - Do not add secrets, generated runtime output, or local environment files. - Frontend commands use Bun only. Do not use `npm`, `pnpm`, or `yarn`. - Run the smallest relevant verification for the changed scope and report anything skipped. --- ## Prohibited - Do not skip visual evidence handling when a visual artifact was provided. - Do not preserve obsolete harness files just because they already exist. - Do not invent behavior not present in code, docs, or verified external sources. - Do not rewrite unrelated files during cleanup. - Do not mark a task complete without checking concrete success criteria.