3.9 KiB
3.9 KiB
Copilot Instructions (Starter)
This file provides default behavior guidance for coding assistants in this repository.
Scope and priorities
- Follow the active implementation checklist in:
- 2026-04-14_StemEngine_Implementation_Checklist_Priority_v1.md
- Prefer smallest safe change that satisfies the requested item.
- 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.mddocs/agents/agency-agents/index.mddocs/agents/agency-agents/MAPPING.mddocs/agents/agency-agents/adapted/docs/agents/agency-agents/upstream/docs/agents/agency-overrides/README.mddocs/agents/agency-overrides/frontend.mddocs/agents/agency-overrides/backend.mddocs/agents/agency-overrides/security.mddocs/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:
- 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
- Pick one primary specialist persona per task; optionally add one reviewer persona.
- Keep outputs checklist-first and implementation-focused for StemEngine.
- Prefer concrete deliverables (file edits, tests, validation) over generic guidance.
- Preserve existing StemEngine conventions and release-gate requirements in this file.
- 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/.