planet/AGENTS.md

Planet Agent Entry Point

This is the compatibility entry point for coding agents. The older root agents.md file remains authoritative for repository-specific agent behavior; do not delete or replace it.

Read First

Read these files before changing code:

1. rules.md - mandatory repository rules. Always load core, security, and workflow; load docs, frontend, backend, earth, ai, or release when the task touches those areas.
2. agents.md - existing agent role, communication, and workflow guidance.
3. project_context.md - static project background. Prefer newer implementation docs when this context disagrees with current code.
4. README.md - current architecture, startup, and toolchain summary.
5. docs/HARNESS.md - harness workflow, conflict policy, and validation tiers.
6. CODEMAP.md - codebase entry points, ownership boundaries, and deeper docs.

For documentation work, also read docs/documentation-coverage-rules.md.

Start Safely

Before editing:

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 the quick check and the frontend Bun build. Docker image smoke builds are intentionally opt-in:

PLANET_HARNESS_DOCKER_SMOKE=1 scripts/harness/validate.sh

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

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.