116 lines
3.9 KiB
Markdown
116 lines
3.9 KiB
Markdown
# 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 <files>)
|
|
- 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/`.
|