planet/docs/HARNESS.md

Agent Harness

This harness improves discoverability, repeatability, and agent safety for the existing Planet project. It does not replace current project rules, scripts, CI, or release workflows.

Authority And Conflicts

Existing project rules are authoritative:

1. rules.md
2. agents.md
3. Current implementation docs under docs/technical/
4. Existing scripts, especially planet.sh
5. Existing Gitea workflow files under .gitea/workflows/

When harness guidance conflicts with any of the above, keep the existing rule, do not overwrite the existing workflow, and add a compatibility note here or in docs/harness-audit.md.

Starting Work

Recommended startup flow:

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

Then read only the relevant implementation docs:

• Backend/API/data work: docs/technical/zh/backend-*.md and matching English docs when public docs are affected.
• Frontend/admin work: docs/technical/zh/frontend-admin-frontend-context.md.
• Earth work: docs/technical/zh/earth-frontend-context.md, docs/technical/zh/earth-render-layer-order.md, and style docs when visual semantics change.
• Operations work: docs/technical/zh/ops-runbook.md and docs/technical/zh/ops-planet-sh-startup.md.
• AI Provider work: docs/technical/zh/agents-aiprovider.md.
• Documentation work: docs/documentation-coverage-rules.md.

Use focused inspection commands before broad reads:

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

Existing Commands

Purpose	Command
First setup	./planet.sh init
Start local stack	./planet.sh start
Start with LAN access	./planet.sh start --allow-lan
Restart all services	./planet.sh restart
Restart one area	./planet.sh restart -b, -f, -a, or -d
Health check	./planet.sh health
Logs	./planet.sh log, ./planet.sh log -b, -f, -a, or -m
Create local user	./planet.sh createuser
Destructive local reset	./planet.sh destroy
Backend smoke tests	cd backend && uv run --frozen --group dev --project .. python -m pytest -s tests/test_api.py tests/test_realtime_sources.py -q
Frontend build	cd frontend && bun install --frozen-lockfile && bun run build
Mock AIS WebSocket	bun run mock:ais-ws

Harness Commands

Tier	Command	What It Does
Doctor	scripts/harness/doctor.sh	Checks required files, required tools, optional delivery tools, and forbidden frontend lockfiles.
Quick	scripts/harness/quick-check.sh	Runs doctor, whitespace diff check, shell syntax checks, and CI backend smoke tests.
Full	scripts/harness/validate.sh	Runs quick check, frontend Bun install/build, optional Helm checks, and opt-in Docker image smoke builds.

Docker image smoke builds are expensive and are off by default:

PLANET_HARNESS_DOCKER_SMOKE=1 scripts/harness/validate.sh

Environment Requirements

Required for normal development:

• zsh for planet.sh
• uv for Python dependency and test execution
• bun for frontend dependency and build execution
• Python resolved by uv from the root pyproject.toml

Required for full local stack operation:

• Docker and Docker Compose
• PostgreSQL and Redis containers started by planet.sh

Optional for delivery smoke:

• Docker daemon for image builds
• Helm for chart lint/template checks

If a required local tool is missing, do not install system software automatically. Report the gap and point to ./planet.sh init or scripts/bootstrap-dev.sh as the existing bootstrap path.

What Agents Must Not Change Automatically

• Do not replace Bun with npm, pnpm, or yarn.
• Do not migrate CI from .gitea/workflows/ to .github/workflows/.
• Do not rewrite planet.sh lifecycle behavior as a parallel script.
• Do not run ./planet.sh destroy unless explicitly requested.
• Do not commit .env, secrets, private keys, logs, or generated build output.
• Do not add external integrations, hooks, or new dependency managers just to satisfy harness structure.
• Do not publish internal harness docs into the product Docs UI unless a maintainer explicitly asks for it.

Hooks And Reminders

No automatic hooks are installed in this phase. Manual reminders:

• Run scripts/harness/quick-check.sh before handing off small changes.
• Run scripts/harness/validate.sh before larger cross-subsystem changes.
• Add focused tests before modifying backend service behavior or frontend workflows.
• For docs changes, run the checks listed in docs/documentation-coverage-rules.md.

Reusable Workflows

Feature Work

1. Read rules.md modules for the touched area.
2. Check CODEMAP.md for entry points and ownership boundaries.
3. Inspect existing tests and docs before editing.
4. Make the smallest behavior-preserving or feature-scoped change.
5. Run scripts/harness/quick-check.sh or a narrower documented command.
6. Update relevant docs when behavior, workflow, or operations change.

Bug Fix

1. Reproduce with a focused test or command.
2. Patch the owning module, not a caller-side workaround.
3. Run the focused regression test.
4. Run scripts/harness/quick-check.sh when the change is safe to validate locally.

Documentation Change

1. Read docs/documentation-coverage-rules.md.
2. Route docs by audience: UI users, operations, or second-party developers.
3. Keep Chinese and English public docs consistent when a public doc pair exists.
4. Run the repository-specific docs checks that match the changed files.

Release Or Delivery Change

Use the existing release skill/workflow and .gitea/workflows/ files. Harness validation can smoke-check Helm and Docker locally, but it must not replace the release process.

Implementation Notes

• docs/harness-audit.md records the discovery pass that led to this harness.
• AGENTS.md is a compatibility entry point for tools that expect the uppercase filename. The existing agents.md file remains in place.
• CODEMAP.md is intentionally high level; deeper subsystem docs stay in docs/technical/{zh,en}/.