# Reference template — `<your-agent-name>`

> **Spec version:** 1.0.0 — see [`../SPEC.md`](../SPEC.md)

A working, copy-and-fill skeleton for a new Python/Starlette agent that conforms to the harness spec.

## Quickstart

```bash
# 1. Copy the template
cp -r template/ ../my-new-agent/
cd ../my-new-agent

# 2. Rename placeholders
git grep -l '<agent-name>\|<agent_name>\|<AgentName>\|<role>' | xargs sed -i \
  -e 's/<agent-name>/my-new-agent/g' \
  -e 's/<agent_name>/my_new_agent/g' \
  -e 's/<AgentName>/MyNewAgent/g' \
  -e 's/<role>/my-new-agent/g'

# 3. Pin the initial version
echo "0.1.0" > .image-version

# 4. Add your domain code
#    - Replace the `/echo` route in app/agent.py with your endpoints
#    - Add your skills to app/skills.py
#    - Add custom metrics to app/metrics.py

# 5. Configure local dev
cp .env.local.example .env.local
# edit .env.local with your secrets

# 6. Run locally
./scripts/deploy-local.sh

# 7. Build & deploy to the cluster
./scripts/full-deploy.sh
```

## What's in the box

```
template/
├── .env.local.example       # all env vars the agent reads, with safe defaults
├── .gitignore
├── .image-version           # 0.1.0
├── Dockerfile               # python:3.12-slim, non-root, HEALTHCHECK
├── README.md                # (this file)
├── requirements.txt         # harness floor + LLM stack
├── app/
│   ├── __init__.py
│   ├── agent.py             # Starlette entry point, all required routes,
│   │                        #   lifespan + self-registration, _skill_dict helper
│   ├── logging_setup.py     # OTel log bridge (copy verbatim — do not edit)
│   ├── metrics.py           # Meter + example counter/histogram
│   └── skills.py            # AGENT_SKILLS list + AGENT_CONFIG dict
├── k8s/
│   ├── configmap.yaml       # REGISTRY_URL, AGENT_SELF_URL, LOG_LEVEL, PORT
│   └── deployment.yaml      # Deployment + Service, OTel annotations + env block
└── scripts/
    ├── deploy.sh            # az acr build + kubectl apply + rollout
    ├── deploy-local.sh      # docker/podman + .env.local
    └── full-deploy.sh       # preflight + deploy.sh + post-deploy smoke
```

## Editing rules

| Touch freely | Touch carefully | Do not edit |
|---|---|---|
| `app/skills.py` | `app/agent.py` (keep lifespan + registration + manifest intact) | `app/logging_setup.py` |
| `app/metrics.py` (rename instruments to your domain) | `k8s/deployment.yaml` env vars (only change `OTEL_*` values, not keys) | The `_skill_dict` helper in `app/agent.py` |
| `requirements.txt` (add your domain deps) | `Dockerfile` (only change `EXPOSE` and the uvicorn port) | `scripts/deploy.sh` flow |
| `k8s/configmap.yaml` data section | `k8s/deployment.yaml` probes (only `initialDelaySeconds` for slow startup) | OTel annotations on the pod template |

## Conformance

Before opening a PR for your new agent, walk the [conformance checklist](../SPEC.md#conformance-checklist) in `SPEC.md`. The reference template ticks every box out of the box; you should only need to verify your domain-specific additions don't regress anything.