# AGENTS.md

This file is the entrypoint for agent work in this repository.
It is intentionally short and points to deeper source-of-truth docs.

## Mission

Maintain `clinic`, a Go CLI for TiDB Cloud Clinic APIs, with behavior that is:

- predictable for users,
- easy for agents to modify safely,
- backed by tests and explicit docs.

## Start Here

1. Read [`docs/INDEX.md`](docs/INDEX.md) for the doc map.
2. If the task needs a multi-step implementation plan, read [`PLANS.md`](PLANS.md) and follow it.
3. Run `make help` to see local verification commands.
4. For code changes, run the narrowest tests first, then `make verify`.

## Repo Map

- `cmd/clinic/main.go`: process entrypoint.
- `internal/cmd/`: command routing, help text, flag parsing, output formatting.
- `internal/config/`: config persistence and environment resolution.
- `internal/clinic/`: HTTP client abstraction and error contract.
- `PLANS.md`: required format and workflow for execution plans.
- `docs/`: architecture map, command surface map, and agent principles.
- `scripts/check-agent-legibility.sh`: mechanical checks for agent-facing docs.

## High-Value Docs

- [`docs/INDEX.md`](docs/INDEX.md): table of contents and ownership.
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md): package boundaries and request flow.
- [`docs/COMMAND_SURFACE.md`](docs/COMMAND_SURFACE.md): command families and edit impact map.
- [`docs/GOLDEN_PRINCIPLES.md`](docs/GOLDEN_PRINCIPLES.md): legibility rules for future edits.
- [`PLANS.md`](PLANS.md): source of truth for writing and maintaining execution plans.

## Guardrails

- Keep this file short. Put details in `docs/` and link from here.
- Do not introduce hidden behavior. If behavior is non-obvious, document it.
- Prefer small focused changes with tests in the same area.
- Preserve existing UX contracts unless the task explicitly changes them.
- When writing plans, follow `PLANS.md` exactly and create plan files in `docs/`.
- When implementing multi-subtask plans, follow the `PLANS.md` subtask execution protocol (fresh non-inherited subagent per subtask, sequential execution, commit after each subtask).
- Use descriptive commit messages that summarize the actual change and scope; avoid generic messages like "update files" or "chore".
- Every `docs/*-plan.md` file must include `## Execution Protocol (Mandatory)` near the top, with explicit subagent/delegation and commit-boundary rules.

## Planning Workflow

- Use `PLANS.md` whenever authoring or updating an execution plan.
- Save plans under `docs/` (for example, `docs/YYYY-MM-DD-<topic>-plan.md`).
- Keep plans self-contained and continuously updated as work progresses.
- When asking an agent to implement a plan, explicitly authorize delegation in the prompt. Template:
  - `Implement <plan-path> using fresh non-inherited subagents per subtask, sequentially, with parent review/integration, one commit per subtask, and Progress updates after each subtask commit.`

## Common Change Paths

- New flag or subcommand:
  - update the relevant `internal/cmd/*.go` handler,
  - update help text in `internal/cmd/help.go`,
  - add/adjust tests in `internal/cmd/*_test.go`,
  - update [`docs/COMMAND_SURFACE.md`](docs/COMMAND_SURFACE.md).
- Config behavior change:
  - update `internal/config/config.go` and tests,
  - document migration or compatibility expectations.
- HTTP behavior change:
  - update `internal/clinic/client.go` and tests,
  - preserve structured `HTTPError` behavior unless intentionally revised.

## Verification Ladder

Use the smallest useful rung first:

- package-focused tests, for example:
  - `go test ./internal/cmd -run Loki -v`
  - `go test ./internal/config -v`
  - `go test ./internal/clinic -v`
- repo-level checks:
  - `make legibility-check`
  - `make test`
  - `make verify`

## Definition of Done

A change is complete when:

- tests for changed behavior are green,
- agent-facing docs are updated when needed,
- `make verify` passes locally.