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:

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

Use focused context commands before reading large files:

```bash
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:

```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.