# Copilot Instructions (Starter) This file provides default behavior guidance for coding assistants in this repository. ## Scope and priorities 1. Follow the active implementation checklist in: - 2026-04-14_StemEngine_Implementation_Checklist_Priority_v1.md 2. Prefer smallest safe change that satisfies the requested item. 3. Preserve existing public APIs and file formats unless the checklist item explicitly requires a change. ## Project structure cues - Backend: backend/ (FastAPI, Python services) - Frontend: frontend/ (React + TypeScript + Vite) - Plans and audits: docs/plans/, 2026-04-14_StemEngine_Audit.md - Change logs: - 20260313_Fixes (Copilot).md - SUMMARIES (Claude).md ## Required validation after edits - Frontend edits: - Run: npm run -s typecheck (from frontend/) - Backend Python edits: - Run compile/syntax checks for touched files (for example: python3 -m compileall ) - If checklist status is changed, ensure notes are updated in the checklist section. ## Coding conventions - TypeScript: - Avoid any and unsafe non-null assertions unless unavoidable. - Prefer shared types from existing central type modules. - Python: - Do not introduce bare except. - Prefer structured logging over print in runtime services. - Keep style and naming consistent with neighboring code. ## Visualizer-specific notes - Vendored fluid runtime is authoritative: - frontend/src/components/visualizers/fluid/webgl-fluid.mjs - Do not reintroduce npm dependency for webgl-fluid unless explicitly requested and migration-safe. - Preserve the direct splat patch contract used by fluidSim.ts. ## Documentation update policy For substantial implementation changes, append concise entries to: - 20260313_Fixes (Copilot).md - SUMMARIES (Claude).md Include: what changed, why, files touched, and validation outcome. ## Optional extended playbooks If you keep larger playbooks, place them in docs/agents/ and reference them here. Only repository-local files are guaranteed to be consistently available in assistant context. Current repo-local scaffold: - `docs/agents/agency-agents/README.md` - `docs/agents/agency-agents/index.md` - `docs/agents/agency-agents/MAPPING.md` - `docs/agents/agency-agents/adapted/` - `docs/agents/agency-agents/upstream/` - `docs/agents/agency-overrides/README.md` - `docs/agents/agency-overrides/frontend.md` - `docs/agents/agency-overrides/backend.md` - `docs/agents/agency-overrides/security.md` - `docs/agents/agency-overrides/release-gate.md` ## Agency Agents integration (msitarzewski/agency-agents) Use The Agency specialist patterns for task routing in this repo. - Upstream reference: - https://github.com/msitarzewski/agency-agents - If cloned locally for this repo, prefer: - `docs/agents/agency-agents/**` - `docs/agents/agency-overrides/**` (repo-specific overrides) ### Specialist routing defaults - Frontend React/TS/Vite work: - Frontend Developer - Backend API/data architecture work: - Backend Architect - Security-sensitive changes: - Security Engineer - Performance hot paths: - Performance Benchmarker - Refactors/architecture proposals: - Software Architect - QA/regression validation planning: - Evidence Collector + Reality Checker - Documentation updates: - Technical Writer ### Operating rules with agency specialists 1. Pick one primary specialist persona per task; optionally add one reviewer persona. 2. Keep outputs checklist-first and implementation-focused for StemEngine. 3. Prefer concrete deliverables (file edits, tests, validation) over generic guidance. 4. Preserve existing StemEngine conventions and release-gate requirements in this file. 5. When specialist guidance conflicts with repo rules, repo rules win. ### Optional local install paths (developer machine) If using global Copilot agent installs, The Agency README documents: - `~/.github/agents/` - `~/.copilot/agents/` For reliable repository behavior, mirror only needed agents into `docs/agents/agency-agents/`.