Files
stemengine_old/.github/copilot-instructions.md
2026-04-14 16:32:36 +09:00

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/`.