# AGENTS.md — autopilot

See [README](README.md) for project overview and capability reference.

## Execution model

This is a **uv script project**, not a Python package. There is no `pyproject.toml`.  
Dependencies are declared in the [PEP 723](https://peps.python.org/pep-0723/) inline metadata block at the top of each script. `uv run` reads that block and auto-installs deps before running.

**To add a runtime dependency**: edit the `dependencies = [...]` block in the relevant script's header, not a requirements file.

## Commands

All `make` targets must be run from this directory.

```bash
make fmt        # autoflake → isort → black (in that order)
make check      # flake8; ignores E203, W291, E501, W503 — long lines are allowed
make typecheck  # mypy, entry point is main.py; deps are auto-sourced from main.py header
```

`make typecheck` shells out to `uv run --with mypy -m mypy main.py` with `--with` flags auto-parsed from the PEP 723 block — it does **not** use a separate mypy config or requirements file.

## Command timeouts

When running the real agent with `uv run main.py <issue_number>`, allow a very long timeout.
The agent may need to wait for GitHub workflows or follow-up status checks before it can
post the final issue comment.

Use at least a 1 hour timeout for real issue handling commands, and prefer longer when
the workflow is known to run slowly. Shorter timeouts can kill the local agent process
before it posts the final diagnosis comment.

## Runtime prerequisites

The `gh` CLI must be installed and authenticated for any agent that calls GitHub Actions workflows.

## Environment variables

| Variable | Purpose | Default |
|---|---|---|
| `MODEL` | Model string (`provider:model-id`) | `bedrock:global.anthropic.claude-sonnet-4-6` |
| `BEDROCK_AWS_PROFILE` | Named AWS profile for Bedrock (use this OR AKSK, not both) | — |
| `BEDROCK_AWS_ACCESS_KEY_ID` / `BEDROCK_AWS_SECRET_ACCESS_KEY` / `BEDROCK_AWS_SESSION_TOKEN` | Bedrock credentials (isolated from default chain) | — |
| `BEDROCK_AWS_REGION` | Bedrock region | `us-east-1` |
| `GITHUB_LOGIN` | Override `gh api user` lookup (required for evals/tests) | from `gh` CLI |
| `LOGFIRE_TOKEN` | Send agent traces to Logfire | — |
| `LOGFIRE_READ_TOKEN` | Query Logfire via SQL (for eval inspection) | — |

Bedrock credentials are intentionally isolated from the default AWS credential chain so skill scripts and utility scripts can use the default profile for cloud access.

## Model selection

The model is a plain string passed to `Agent(...)`. Format: `provider:model-id`.  
Supported providers (from the `pydantic-ai-slim` extras in `main.py`): `openrouter`, `bedrock`.

## Entry points

| Command | Effect |
|---|---|
| `uv run main.py <issue_number>` | Run `diagnose_agent` on a pre-created diagnosis issue |
| `uv run main.py` | Start `chat_agent` web UI at `http://127.0.0.1:7932` |

`diagnose_agent` is stateless across restarts: it re-reads the diagnosis issue on each invocation and updates the issue comment with its findings.

Sibling-repo paths (`app-delivery`, `observability`) are resolved in `config.py` by going three levels up from `autopilot/config.py` (`<base>/auto-deploy/autopilot/`). Both repos are expected as `<base>/app-delivery/` and `<base>/observability/`.

## Agent instructions

System prompts live in the `instructions/` directory and use `string.Template` syntax (`${variable}`).

| File | Used by | Description |
|---|---|---|
| `instructions/diagnose.tmpl` | `diagnose_agent` | Workflow failure diagnosis agent prompt |
| `instructions/chat.tmpl` | `chat_agent` | Interactive dev/debug chat UI prompt |

Both templates are substituted at import time in `agent.py` using these four variables:

| Variable | Source |
|---|---|
| `${github_login}` | `config.GITHUB_LOGIN` — resolved from `gh api user` or `$GITHUB_LOGIN` env var |
| `${auto_deploy_dir}` | `config.AUTO_DEPLOY_DIR` — absolute path to the local `auto-deploy` checkout |
| `${app_delivery_dir}` | `config.APP_DELIVERY_DIR` — absolute path to the local `app-delivery` checkout |
| `${observability_dir}` | `config.OBSERVABILITY_DIR` — absolute path to the local `observability` checkout |

All three repos (`auto-deploy`, `app-delivery`, `observability`) are under the `tidbcloud` GitHub org and are private. The agent accesses them read-only (source browsing and log correlation only).

To change agent behavior, edit the relevant `.tmpl` file directly — no Python changes needed.

## Querying Logfire

Eval results and agent traces are sent to Logfire. Use the `query-logfire` skill to run SQL queries against them.

If you need to inspect agent or eval logs to understand a failure, prefer the `query-logfire` skill before doing broader manual digging.

Requires the `LOGFIRE_READ_TOKEN` environment variable. Key patterns:

- Eval case spans are named `case: {case_name}`; the `attributes` JSONB column contains `case_name` and `assertions`
- Find failing cases: filter `attributes->>'assertions' LIKE '%"value": false%'`

See [logfire-query skill](../.github/skills/logfire-query/SKILL.md) for full examples and schema reference.

## Type-check notes

`make typecheck` passes with zero errors. `import-untyped` warnings for `pydantic_ai_backends` are suppressed via `--disable-error-code=import-untyped` in the Makefile (no upstream stubs exist). All other mypy errors should be zero.

## Skills

`skills/` contains autopilot skill guides and executable scripts.

Each skill is a directory with:
- `SKILL.md` — YAML frontmatter (`name`, `description`) + markdown instructions
- Optional scripts in `scripts/` subdirectory (`.py`, `.sh`, etc.)

Python skill scripts use `#!/usr/bin/env -S uv run -q` + PEP 723 inline metadata to manage their own dependencies independently of `main.py`.

Current skills:

| Skill | Description |
|---|---|
| `debug-workflow` | Investigate workflow failures and triage root causes |
| `argocd-apps` | Read ArgoCD app status from GKE via kubectl (no ArgoCD CLI or SSO needed) |
| `create-skill` | Authoring guide for new skills |

## scripts/

`scripts/` contains standalone utility scripts that are not autopilot skills.

| Script | Description |
|---|---|
| `run-weekly-test.py` | Dispatches deploy then destroy for each entry in `test-configs.yaml` in parallel. Used by the `weekly-test.yml` GitHub Actions workflow. Exits 0 if all pass, 1 if any fail. Requires `gh` CLI installed and `GH_TOKEN` set. |

`test-configs.yaml` holds the list of region configurations exercised by the weekly test.

## Capabilities

`capabilities/` contains general-purpose tool modules registered on each agent.

## Related Documentation

- [README](README.md) — full project overview, workflow routing table, flow descriptions, capability and skill reference
- [skills/debug-workflow/SKILL.md](skills/debug-workflow/SKILL.md)
- [skills/argocd-apps/SKILL.md](skills/argocd-apps/SKILL.md)
- [skills/create-skill/SKILL.md](skills/create-skill/SKILL.md)