Contributing for Agents

Contributing for Agents

Rules for AI coding agents (and humans) working in the COMSTAR repo. Source: AGENTS.md.

---

Contracts first

Read Contracts / docs/CONTRACTS.md before changing any cross-process interface. Update the contract, then code, then tests — in that order.

---

Milestone order

Work Milestones in order (M0 → M9). Do not start M(n+1) until M(n) exit criteria are met. Track status in Progress Tracker.

---

Structured logs

Every process emits one JSON object per line:

Field	Required	Meaning
ts	yes	epoch ms
level	yes	debug, info, warn, error
proc	yes	bridge, audio, kiosk
evt	yes	event name
msg	yes	human-readable summary
turn_id	no	active turn ULID
data	no	structured payload

Level from COMSTAR_LOG (default info).

---

Latency spans

Emit on close via the Span helper. Standard names: wake_to_listen, stt, orchestration, tts_first, tts_total, avatar_start, turn_total.

→ Latency Budget

---

LAN binding

See Security — triple gate.

---

Architecture (speech vs brain)

• On Pi: capture, VAD, wake word, kiosk, playback.
• On AI server: AO Reach (incl. optional speech sidecars) + CodeProject.AI.
• Prefer SessionBridge.speechClient when AO ≥ 1.28 advertises hello.speech; else COMSTAR_STT_URL / COMSTAR_TTS_URL.
• Do not ferry PCM on the Reach WebSocket or route turns through the planner just for STT (ADR 0003).
• STT accuracy: label live bridge fixtures (testdata/stt/). Parecord goldens are smoke-only.

---

Secrets

Never commit tokens, keys, real config YAML, or comstar.mac.env. Use examples.

---

Related pages

• Contracts
• Implementation Plan
• Dev Loop
• Security