# agent-harness-spec

Standard definition and reference template for **Python/Starlette agents** running on the platform.

This repository defines:

1. The **normative contract** every platform agent must conform to — see [SPEC.md](SPEC.md).
2. A working **reference template** under [`template/`](template/) you copy when starting a new agent.
3. **Deep-dive docs** under [`docs/`](docs/) covering registration, observability, the agent manifest, Kubernetes shape, and deployment.

The spec is derived from the production agents shipped in `cjot-backstage-az/agents/` (branch `sandbox/jonathan`) — `agent-registry`, `golden-path`, `policy-transformer`, `modernization-factory-v2`, `scaffold-agent`, `decomposer`, `discovery-agent`, `the-watcher`, `support-intake-agent`, etc. If an agent in that repository disagrees with this spec, the spec wins on net-new work; existing deviations are tracked under [`docs/deviations.md`](docs/deviations.md) and brought into line at the next minor version bump.

## When to use this repo

- **Starting a new agent**: `cp -r template/ ../my-new-agent/` and follow [`template/README.md`](template/README.md).
- **Auditing an existing agent**: walk the [conformance checklist](SPEC.md#conformance-checklist) in `SPEC.md`.
- **Changing the contract**: open a PR against `SPEC.md` + bump the spec version in [CHANGELOG.md](CHANGELOG.md).

## Spec version

The current spec version is **`1.0.0`** (see [CHANGELOG.md](CHANGELOG.md)).

## Quick links

| Topic | File |
|---|---|
| Normative contract | [SPEC.md](SPEC.md) |
| Self-registration with the gateway | [docs/registration.md](docs/registration.md) |
| OpenTelemetry wiring (logs / metrics / traces) | [docs/observability.md](docs/observability.md) |
| `/.well-known/agent.json` manifest schema | [docs/manifest.md](docs/manifest.md) |
| Kubernetes deployment shape | [docs/kubernetes.md](docs/kubernetes.md) |
| Build & deploy flow (ACR, scripts, `.image-version`) | [docs/deployment.md](docs/deployment.md) |
| Known deviations from the spec | [docs/deviations.md](docs/deviations.md) |
| Reference template walkthrough | [template/README.md](template/README.md) |