Skip to content

Commit a0808c9

Browse files
jerome-benoitjerome-benoit
committed
chore: add coding agents configuration
Signed-off-by: Jérôme Benoit <[email protected]>
1 parent b0377b6 commit a0808c9

File tree

2 files changed

+239
-0
lines changed

2 files changed

+239
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# Copilot Instructions (repository-wide, language-agnostic)
2+
3+
These instructions guide GitHub Copilot to generate changes consistent with this
4+
repository's conventions, regardless of programming language.
5+
6+
## Glossary
7+
8+
- **Tunables**: user-adjustable parameters that shape behavior, exposed via
9+
options or configuration files.
10+
- **Canonical defaults**: the single, authoritative definition of all tunables
11+
and their defaults.
12+
13+
## Implementation guidance for Copilot
14+
15+
- **Before coding**:
16+
- Perform a comprehensive inventory of the codebase. Search for and read:
17+
- README.md, CONTRIBUTING.md, and all other documentation files.
18+
- code files related to the task.
19+
- Identify existing code architecture, design patterns, canonical defaults,
20+
naming patterns and coding styles.
21+
- **When coding**:
22+
- Follow the core principles and TypeScript/Node.js conventions below.
23+
- Follow identified design patterns, naming patterns and coding styles.
24+
- **After coding**:
25+
- Ensure changes pass quality gates below.
26+
- **When adding a tunable**:
27+
- Add to canonical defaults with safe value.
28+
- Ensure the options and configuration section below is respected.
29+
- Update documentation and serialization.
30+
- **When implementing analytical methods**:
31+
- Follow statistical conventions below.
32+
- **When refactoring**:
33+
- Keep public APIs stable; provide aliases if renaming unless explicitly
34+
requested.
35+
- Update code, tests, and documentation atomically.
36+
- **When documenting**:
37+
- Follow documentation conventions below.
38+
39+
## Core principles
40+
41+
- **Design patterns**: prefer established patterns (e.g., factory, singleton,
42+
strategy) for code organization and extensibility.
43+
- **Algorithmic**: prefer algorithms or heuristics solving the problem while
44+
minimizing time and space complexity.
45+
- **DRY**: avoid duplication of logic, data, and naming. Factor out
46+
commonalities.
47+
- **Single source of truth**: maintain a canonical defaults map for
48+
configuration tunables. Derive all user-facing options automatically.
49+
- **Naming coherence**: prefer semantically accurate names across code,
50+
documentation, directories, and outputs. Avoid synonyms that create ambiguity.
51+
- **English-only**: code, tests, logs, comments, and documentation must be in
52+
English.
53+
- **Small, verifiable changes**: prefer minimal diffs that keep public behavior
54+
stable unless explicitly requested.
55+
- **Tests-first mindset**: add or update minimal tests before refactoring or
56+
feature changes.
57+
- **Documentation standards**: must follow established standards for programming
58+
languages.
59+
60+
## Options and configuration
61+
62+
- **Dynamic generation**: derive CLI and configuration options automatically
63+
from canonical defaults. Avoid manual duplication.
64+
- **Merge precedence**: defaults < user options < explicit overrides (highest
65+
precedence). Never silently drop user-provided values.
66+
- **Validation**: enforce constraints (choices, ranges, types) at the option
67+
layer with explicit typing.
68+
- **Help text**: provide concrete examples for complex options, especially
69+
override mechanisms.
70+
71+
## Statistical conventions
72+
73+
- **Hypothesis testing**: use a single test statistic (e.g., t-test) when
74+
possible.
75+
- **Divergence metrics**: document direction explicitly (e.g., KL(A||B) vs
76+
KL(B||A)); normalize distributions; add numerical stability measures.
77+
- **Effect sizes**: report alongside test statistics and p-values; use standard
78+
formulas; document directional interpretation.
79+
- **Distribution comparisons**: use multiple complementary metrics (parametric
80+
and non-parametric).
81+
- **Multiple testing**: document corrections or acknowledge their absence.
82+
83+
## Reporting conventions
84+
85+
- **Structure**: start with run configuration, then stable section order for
86+
comparability.
87+
- **Format**: use structured formats (e.g., tables) for metrics; avoid free-form
88+
text for data.
89+
- **Interpretation**: include threshold guidelines; avoid overclaiming
90+
certainty.
91+
- **Artifacts**: timestamp outputs; include configuration metadata.
92+
93+
## Documentation conventions
94+
95+
- **Clarity**: plain, unambiguous language; avoid marketing jargon and
96+
speculation.
97+
- **Concision**: remove boilerplate; state facts directly without redundant
98+
phrasing.
99+
- **Structure**: use consistent section ordering; follow stable patterns for
100+
comparable content.
101+
- **Timeliness**: document current state; exclude historical evolution (except
102+
brief API breaking change notes).
103+
- **Terminology**: use correct and consistent terminology; distinguish clearly
104+
between related concepts.
105+
- **Exhaustivity**: cover all user-facing behavior and constraints; omit
106+
internal implementation details unless necessary for usage.
107+
- **Pertinence**: include information that aids understanding or usage; remove
108+
tangential content.
109+
- **No duplication**: maintain single authoritative documentation source;
110+
reference other sources rather than copying.
111+
112+
Documentation serves as an operational specification, not narrative prose.
113+
114+
## TypeScript conventions
115+
116+
- **Naming**: Use camelCase for variables/functions/methods, PascalCase for
117+
classes/types/enums/interfaces.
118+
- **Async operations**: Prefer async/await over raw Promises; handle rejections
119+
explicitly with try/catch.
120+
- **Error handling**: Use typed errors with structured properties when
121+
applicable.
122+
- **Worker communication**: Use broadcast channels for decoupled worker<->main
123+
thread messaging.
124+
- **Null safety**: Avoid non-null assertions (!); use optional chaining (?.) and
125+
nullish coalescing (??).
126+
- **Type safety**: Prefer explicit types over any; use type guards and
127+
discriminated unions where appropriate.
128+
- **Promise patterns**: Return Promises from async operations; store
129+
resolvers/rejectors in Maps for request/response flows.
130+
- **Immutability**: Avoid mutating shared state; clone objects before
131+
modification when needed.
132+
133+
## Quality gates
134+
135+
- Documented build/lint/type checks pass (where applicable).
136+
- Documented tests pass (where applicable).
137+
- Documentation updated to reflect changes when necessary.
138+
- Logs use appropriate levels (error, warn, info, debug).
139+
- Pull request title and commit messages follow
140+
[Conventional Commits](https://www.conventionalcommits.org/) format.
141+
142+
## Examples
143+
144+
### Naming coherence
145+
146+
**Good** (consistent style, clear semantics):
147+
148+
```typescript
149+
const thresholdValue = 0.06
150+
const processingMode = 'piecewise'
151+
type ChargingStationStatus = 'Available' | 'Preparing' | 'Charging'
152+
```
153+
154+
**Bad** (mixed styles, ambiguous):
155+
156+
```typescript
157+
const threshold_value = 0.06 // inconsistent case style
158+
const thresholdAim = 0.06 // synonym creates ambiguity
159+
type charging_station_status // wrong casing for type
160+
```
161+
162+
### Promise-based request/response pattern
163+
164+
**Good** (proper async flow):
165+
166+
```typescript
167+
protected handleProtocolRequest(
168+
uuid: string,
169+
procedureName: ProcedureName,
170+
payload: RequestPayload
171+
): Promise<ResponsePayload> {
172+
return new Promise<ResponsePayload>((resolve, reject) => {
173+
this.pendingRequests.set(uuid, { reject, resolve })
174+
this.sendBroadcastChannelRequest(uuid, procedureName, payload)
175+
})
176+
}
177+
```
178+
179+
**Bad** (returns void, no Promise):
180+
181+
```typescript
182+
protected handleProtocolRequest(
183+
uuid: string,
184+
procedureName: ProcedureName,
185+
payload: RequestPayload
186+
): void {
187+
this.sendBroadcastChannelRequest(uuid, procedureName, payload)
188+
// Response never reaches caller!
189+
}
190+
```
191+
192+
### Statistical reporting
193+
194+
```markdown
195+
| Metric | Value | Interpretation |
196+
| ----------- | ----- | --------------------- |
197+
| KL(A‖B) | 0.023 | < 0.1: low divergence |
198+
| Effect size | 0.12 | small to medium |
199+
```
200+
201+
---
202+
203+
By following these instructions, Copilot should propose changes that are
204+
consistent and maintainable across languages.

‎AGENTS.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Agent Guidelines for Poolifier Web Worker
2+
3+
## Build/Test Commands
4+
5+
- **Test**: `deno task test` (all tests), `deno task test:parallel` (all tests
6+
in parallel), `deno task test:coverage` (with coverage)
7+
- **Single test**: `deno test -A tests/path/to/specific.test.mjs`
8+
- **Lint**: `deno task lint` (check), `deno task lint:fix` (autofix)
9+
- **Format**: `deno task format` (autoformat), `deno task format:check` (check
10+
only)
11+
- **Bundle**: `deno task bundle`
12+
- **Coverage**: `deno task coverage:report` (with coverage report)
13+
14+
## Code Style & Conventions
15+
16+
- **Runtime**: Deno with TypeScript, no Node.js dependencies
17+
- **Imports**: Use `.ts` extensions, relative paths from `src/`, group imports
18+
(types, utils, modules)
19+
- **Formatting**: 2-space indentation, single quotes, no semicolons (Deno fmt)
20+
- **Naming**: camelCase (variables/functions), PascalCase
21+
(classes/types/enums/interfaces)
22+
- **Types**: Explicit types over `any`, use type guards, avoid non-null
23+
assertions (`!`)
24+
- **Async**: Prefer async/await, handle rejections with try/catch
25+
- **Error handling**: Typed errors with structured properties
26+
- **Worker patterns**: Broadcast channels for worker communication, store
27+
Promise resolvers in Maps
28+
- **Testing**: Use `@std/expect` and `@std/testing/bdd`, `.mjs` extension for
29+
test files
30+
31+
## Architecture Principles
32+
33+
Follow `.github/copilot-instructions.md`: DRY principle, single source of truth,
34+
design patterns (factory/strategy), algorithmic solutions, minimal time/space
35+
complexity, English-only code/docs, tests-first mindset.

0 commit comments

Comments
 (0)