Add code review instructions and release checklist prompts

.github/instructions/code-review.instructions.md

@@ -0,0 +1,83 @@
+---
+description: "Use when the user asks for a code review, PR review, regression scan, or quality review of backend changes in this repository."
+---
+
+# Code Review Instruction
+
+## Review Objective
+
+Find defects and risks before merge. Prioritize behavior, correctness, reliability, and operational safety over style preferences.
+
+## Output Contract
+
+Return review results in this order:
+
+1. Findings ordered by severity (critical, high, medium, low)
+2. Open questions or assumptions
+3. Brief change summary
+
+If no actionable findings exist, explicitly say no findings and list residual risks or test gaps.
+
+## Finding Format
+
+For each finding include:
+
+- Severity
+- Impact
+- Evidence with file reference
+- Why it matters
+- Suggested fix direction
+
+## Repository-Specific Review Focus
+
+### API Behavior and Compatibility
+
+- Verify route behavior under app/api/routes is compatible with existing endpoint contracts.
+- Check query alias compatibility for upstream params such as BusStopCode, ServiceNo, Date, and $skip.
+- Flag any accidental payload transformation if endpoint should proxy upstream JSON directly.
+
+### Upstream and Error Handling
+
+- Confirm upstream failures are mapped consistently and safely.
+- Ensure no secrets or sensitive payload content is leaked in error bodies.
+- Validate timeout and retry assumptions for DataMall calls.
+
+### Cache Safety
+
+- For cache-related changes, verify key stability, TTL appropriateness, and stale-data risk.
+- Confirm degraded behavior is safe when Valkey is unavailable.
+- Check that cache logic is centralized in app/services/cache.py patterns.
+
+### Configuration and Secrets
+
+- Confirm required env vars are documented in .env.example.
+- Confirm .env is not staged or committed.
+- Verify new settings are wired through app/core/config.py.
+
+### Runtime and Deployment
+
+- Validate Docker and compose changes maintain health endpoint behavior.
+- Ensure Makefile targets still reflect actual workflows.
+- Check operational regressions for Podman or Docker detection logic.
+
+### Tests and Validation
+
+- Require at least compile-level validation for touched Python files.
+- Flag missing automated tests for behavior changes.
+- For major logic changes, request route-level or service-level tests.
+
+## High-Risk Patterns To Flag Immediately
+
+- Breaking endpoint contract changes without documentation updates
+- Silent exception swallowing in request or cache paths
+- Hardcoded secrets or keys
+- Unbounded cache growth patterns
+- Changes that bypass centralized client or cache abstractions
+
+## Helpful References
+
+- Architecture and commands: AGENTS.md
+- Runtime and usage: README.md
+- Entry wiring: app/main.py
+- Upstream client: app/services/lta_client.py
+- Cache layer: app/services/cache.py

.github/prompts/release-checklist.prompt.md

@@ -0,0 +1,53 @@
+---
+mode: ask
+description: "Use when preparing a release for this backend project to run a consistent release checklist covering build, runtime, config safety, and documentation updates."
+---
+
+# Release Checklist
+
+Run a full release readiness pass for this repository.
+
+## Inputs
+
+- Release version or tag
+- Scope of changes
+- Target environment (local, staging, production)
+
+If any input is missing, ask concise follow-up questions before proceeding.
+
+## Checklist Workflow
+
+1. Review changed files and summarize release scope.
+2. Validate project health:
+   - Run make sync if dependency files changed.
+   - Run make compile.
+3. Validate container workflow:
+   - Run make compose-up when Podman or Docker is available.
+   - Verify the health endpoint returns success.
+   - Run make compose-ps and confirm services are healthy.
+4. Validate configuration safety:
+   - Ensure .env is not staged or committed.
+   - Ensure .env.example includes any new required variables.
+5. Validate docs and instructions:
+   - Update README.md if commands, routes, or behavior changed.
+   - Update AGENTS.md if conventions or operational workflows changed.
+6. Produce a release report with:
+   - Pass and fail checklist items
+   - Risks or follow-ups
+   - Suggested next actions before tagging
+
+## Output Format
+
+Return results in this order:
+
+1. Findings by severity, with file references where relevant
+2. Open questions and assumptions
+3. Release readiness verdict: ready, conditionally ready, or not ready
+4. Recommended next actions
+
+## Project-Specific Notes
+
+- Primary commands are managed through Makefile and uv.
+- Backend routes live under app/api/routes.
+- Runtime depends on DATAMALL_API_KEY from .env.
+- Valkey cache is expected in compose-based runs.

.github/skills/backend-testing/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: backend-testing
+description: "Use when adding, fixing, or reviewing backend tests for this FastAPI project, including route tests, service tests, cache behavior, and upstream error handling."
+---
+
+# Backend Testing Skill
+
+Use this skill to design and implement robust tests for the backend API.
+
+## Project Context
+
+- App framework: FastAPI
+- Python environment: uv
+- API routes: [app/api/routes/bus.py](app/api/routes/bus.py)
+- Upstream client: [app/services/lta_client.py](app/services/lta_client.py)
+- Cache layer: [app/services/cache.py](app/services/cache.py)
+- App wiring and lifespan: [app/main.py](app/main.py)
+
+## Testing Goals
+
+1. Verify endpoint behavior, input validation, and response shape.
+2. Verify upstream failures are mapped to expected HTTP errors.
+3. Verify cache-assisted behavior does not break correctness.
+4. Keep tests deterministic with no real external API calls.
+
+## Workflow
+
+1. Identify the change surface and affected endpoints or services.
+2. Add or update tests under a test layout that mirrors app modules.
+3. Mock external dependencies:
+   - Mock DataMall calls from [app/services/lta_client.py](app/services/lta_client.py).
+   - Stub cache interactions from [app/services/cache.py](app/services/cache.py).
+4. Cover at least these scenarios per endpoint:
+   - Success response
+   - Input validation failure
+   - Upstream failure mapping
+5. Run checks and tests with uv.
+6. Keep tests readable with clear arrange, act, assert sections.
+
+## Preferred Patterns
+
+- Use pytest-style tests and fixtures.
+- Use FastAPI test clients for route-level coverage.
+- Keep one behavior assertion focus per test.
+- Use explicit test data, not random values.
+- Name tests with behavior intent, for example: test_bus_arrival_returns_upstream_payload.
+
+## Commands
+
+- Sync dependencies: make sync
+- Compile check: make compile
+- Run tests: uv run pytest
+
+If pytest is not installed yet, add it to project dependencies before creating tests.
+
+## Quality Gate Before Finish
+
+1. New or changed behavior has corresponding tests.
+2. Tests do not call live DataMall services.
+3. Error handling and validation paths are covered.
+4. Existing compile check still passes.