planet/AGENTS.md

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:

git status --short
scripts/harness/doctor.sh

Use focused context commands before reading large files:

rg -n "<symbol-or-term>" <path>
git diff --stat HEAD
git diff --name-only HEAD
git diff --unified=0 HEAD -- <path>

Preserve user changes already present in the worktree.

Validation

Fast local harness validation:

scripts/harness/quick-check.sh

Full local validation:

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:

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.