127 lines
7.0 KiB
Markdown
127 lines
7.0 KiB
Markdown
# Maintaining AI Assistant Instructions (copilot-instructions.md)
|
||
|
||
This repo uses `.github/copilot-instructions.md` to brief AI coding agents about your architecture, workflows, and conventions. Keep it concise, repo-specific, and always in sync with your code.
|
||
|
||
This guide explains when and how to update it, plus small guardrails to help—even for a solo developer.
|
||
|
||
## When to update
|
||
Update the instructions in the same commit as your change whenever you:
|
||
- Add/rename services, ports, or container wiring (docker-compose*.yml, Nginx, Mosquitto)
|
||
- Introduce/rename MQTT topics or change retained-message behavior
|
||
- Add/rename environment variables or change defaults (`.env.example`, `deployment.md`)
|
||
- Change DB models or time/UTC handling (e.g., `models/models.py`, UTC normalization in routes/scheduler)
|
||
- Add/modify API route patterns or session lifecycle (files in `server/routes/*`, `server/wsgi.py`)
|
||
- Adjust frontend dev proxy or build settings (`dashboard/vite.config.ts`, Dockerfiles)
|
||
- Modify scheduler polling, power-intent semantics, or retention strategy
|
||
|
||
## What to update (and where)
|
||
- `.github/copilot-instructions.md`
|
||
- Big picture: services and ports
|
||
- Service boundaries & data flow: DB connection rules, MQTT topics, retained messages, screenshots
|
||
- API patterns: Blueprints, Session per request, enum/datetime serialization
|
||
- Frontend patterns: Vite dev proxy and pre-bundled dependencies
|
||
- Environment variables (reference): names, purposes, example patterns
|
||
- Conventions & gotchas: UTC comparisons, retained MQTT, container hostnames
|
||
- `.env.example`
|
||
- Add new variable names with placeholders and comments (never secrets)
|
||
- Keep in-container defaults (e.g., `DB_HOST=db`, `MQTT_BROKER_HOST=mqtt`)
|
||
- `deployment.md`
|
||
- Update Quickstart URLs/ports/commands
|
||
- Document prod-specific env usage (e.g., `VITE_API_URL`, `DB_CONN`)
|
||
|
||
## How to write good updates
|
||
- Keep it short (approx. 20–50 lines total). Link to code by path or route rather than long prose.
|
||
- Document real, present patterns—not plans.
|
||
- Use UTC consistently and call out any special handling.
|
||
- Include concrete examples from this repo when describing patterns (e.g., which route shows enum serialization).
|
||
- Never include secrets or real tokens; show only variable names and example formats.
|
||
|
||
## Scope boundaries (important)
|
||
To avoid turning `.github/copilot-instructions.md` into a shadow README/changelog, keep clear boundaries:
|
||
- `.github/copilot-instructions.md`: quick operational brief for agents (architecture snapshot, non-negotiable conventions, key paths, critical contracts).
|
||
- `README.md`: project entrypoint and documentation navigation.
|
||
- `TECH-CHANGELOG.md` and `DEV-CHANGELOG.md`: change history and release/development notes.
|
||
- Feature contracts/specs: dedicated files (for example `MQTT_EVENT_PAYLOAD_GUIDE.md`, `TV_POWER_INTENT_SERVER_CONTRACT_V1.md`).
|
||
|
||
Do not place long historical sections, release summaries, or full endpoint catalogs in `.github/copilot-instructions.md`.
|
||
|
||
## Size and quality guardrails
|
||
- Target size for `.github/copilot-instructions.md`: about 120-220 lines.
|
||
- If a new section exceeds ~10 lines, prefer linking to an existing canonical doc instead.
|
||
- Keep each section focused on actionability for coding agents.
|
||
- Remove duplicate rules if already stated in another section.
|
||
- Use concise bullets over long prose blocks.
|
||
|
||
Quick pre-commit check:
|
||
- Is this content a rule/pattern needed during coding now?
|
||
- If it is historical context, move it to changelog/archive docs.
|
||
- If it is deep reference material, move it to the canonical feature doc and link it.
|
||
|
||
## Solo-friendly workflow
|
||
- Update docs in the same commit as your change:
|
||
- Code changed → docs changed (copilot-instructions, `.env.example`, `deployment.md` as needed)
|
||
- Use a quick self-checklist before pushing:
|
||
- Services/ports changed? Update “Big picture”.
|
||
- MQTT topics/retained behavior changed? Update “Service boundaries & data flow”.
|
||
- API/Session/UTC rules changed? Update “API patterns” and “Conventions & gotchas”.
|
||
- Frontend proxy/build changed? Update “Frontend patterns”.
|
||
- Env vars changed? Update “Environment variables (reference)” + `.env.example`.
|
||
- Dev/prod run steps changed? Update `deployment.md` Quickstart.
|
||
- Keep commits readable by pairing code and doc changes:
|
||
- `feat(api): add events endpoint; docs: update routes and UTC note`
|
||
- `chore(compose): rename service; docs: update ports + nginx`
|
||
- `docs(env): add MQTT_USER to .env.example + instructions`
|
||
|
||
## Optional guardrails (even for solo)
|
||
- PR (or MR) template (useful even if you self-merge)
|
||
- Add `.github/pull_request_template.md` with:
|
||
```
|
||
Checklist
|
||
- [ ] Updated .github/copilot-instructions.md (services/MQTT/API/UTC/env)
|
||
- [ ] Synced .env.example (new/renamed vars)
|
||
- [ ] Adjusted deployment.md (dev/prod steps, URLs/ports)
|
||
- [ ] Verified referenced files/paths in the instructions exist
|
||
```
|
||
- Lightweight docs check (optional pre-commit hook)
|
||
- Non-blocking script that warns if referenced files/paths don’t exist. Example sketch:
|
||
```
|
||
#!/usr/bin/env bash
|
||
set -e
|
||
FILE=.github/copilot-instructions.md
|
||
missing=0
|
||
for path in \
|
||
server/wsgi.py \
|
||
server/routes/clients.py \
|
||
server/routes/events.py \
|
||
server/routes/groups.py \
|
||
dashboard/vite.config.ts \
|
||
docker-compose.yml \
|
||
docker-compose.override.yml; do
|
||
if ! test -e "$path"; then
|
||
echo "[warn] referenced path not found: $path"; missing=1
|
||
fi
|
||
done
|
||
exit 0 # warn only; do not block commit
|
||
```
|
||
- Weekly 2-minute sweep
|
||
- Read `.github/copilot-instructions.md` top-to-bottom and remove anything stale.
|
||
|
||
## FAQ
|
||
- Where do the AI assistants look?
|
||
- `.github/copilot-instructions.md` + the code you have open. Keep this file synced with the codebase.
|
||
- Is it safe to commit this file?
|
||
- Yes—no secrets. It should contain only structure, patterns, and example formats.
|
||
- How detailed should it be?
|
||
- Concise and actionable; point to exact files for details. Avoid generic advice.
|
||
|
||
## Pointers to key files
|
||
- Compose & infra: `docker-compose*.yml`, `nginx.conf`, `mosquitto/config/mosquitto.conf`
|
||
- Backend: `server/database.py`, `server/wsgi.py`, `server/routes/*`, `models/models.py`
|
||
- MQTT workers: `listener/listener.py`, `scheduler/scheduler.py`, `server/mqtt_helper.py`
|
||
- Frontend: `dashboard/vite.config.ts`, `dashboard/package.json`, `dashboard/src/*`
|
||
- Dev/Prod docs: `deployment.md`, `.env.example`
|
||
|
||
## Documentation sync log
|
||
- 2026-03-24: Synced docs for completed monitoring rollout and presentation flag persistence fix (`page_progress` / `auto_progress`). Updated `.github/copilot-instructions.md`, `README.md`, `TECH-CHANGELOG.md`, `DEV-CHANGELOG.md`, and `docs/archive/CLIENT_MONITORING_IMPLEMENTATION_GUIDE.md` without a user-version bump.
|
||
- 2026-04-01: Synced docs for TV power intent Phase 1 implementation and contract consistency. Updated `.github/copilot-instructions.md`, `MQTT_EVENT_PAYLOAD_GUIDE.md`, `docs/archive/TV_POWER_PHASE_1_SERVER_HANDOFF.md`, `TECH-CHANGELOG.md`, and `DEV-CHANGELOG.md` to match scheduler behavior (`infoscreen/groups/{group_id}/power/intent`, `schema_version: "1.0"`, transition + heartbeat semantics, poll-based expiry).
|