Create .github/instructions folder with cross-cutting topic instruction files by Copilot · Pull Request #2198 · FlexMeasures/flexmeasures

Copilot · 2026-05-22T22:47:09Z

Explore all agent files to identify cross-cutting topics
Create .github/instructions/ directory with 9 topic-specific <topic>.instructions.md files following GitHub recommendations (with applyTo: frontmatter):
- atomic-commits.instructions.md — commit discipline (applyTo: "**")
- pre-commit-hooks.instructions.md — required hooks workflow (applyTo: "**")
- docstrings.instructions.md — RST docstring format + doctests (applyTo: "**/*.py")
- changelog.instructions.md — entry format and location (applyTo: "**")
- error-handling.instructions.md — specific exception catching (applyTo: "**/*.py")
- ui-terminology.instructions.md — "organisation" not "account" (applyTo: "flexmeasures/ui/**")
- marshmallow-schemas.instructions.md — data_key conventions (applyTo: "flexmeasures/data/schemas/**/*.py")
- timezone-awareness.instructions.md — always timezone-aware datetimes, including in log statements (applyTo: "**/*.py")
- testing.instructions.md — full suite mandatory before session close, db vs fresh_db, requesting_user (applyTo: "flexmeasures/**/tests/**/*.py")
- README.md — documents the folder structure, including step to remove redundant agent sections
Updated all 9 agent files to reference .github/instructions/ for shared cross-cutting conventions
Updated coordinator.md to document the .github/instructions/ structure
Removed redundant sections from all agent files (AGENTS.md, test-specialist.md, coordinator.md, and all other specialist files) — each now replaced with a one-liner pointer to the relevant instruction file
Added changelog entry under Infrastructure / Support in documentation/changelog.rst
All commits are atomic
PR Create .github/instructions folder with cross-cutting topic instruction files #2198 created
Label PR with "AI Infra"

Context: - Every agent file repeats atomic commit requirements in its own section - Extracting to a shared instruction makes it available to all Copilot interactions Change: - Created .github/instructions/atomic-commits.instructions.md - Covers commit granularity, forbidden files, and commit message format Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Context: - pre-commit requirements appear in tooling-ci-specialist, AGENTS.md (Lead), test-specialist, and coordinator — repeated four times across agent files Change: - Created .github/instructions/pre-commit-hooks.instructions.md - Covers setup, mandatory execution, hook descriptions, and openapi caution Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Context: - Docstring conventions appear in documentation-developer-experience-specialist and apply broadly to all Python contributors Change: - Created .github/instructions/docstrings.instructions.md - Covers RST format, parameter alignment, doctests, Click conventions Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Context: - Changelog requirements appear in AGENTS.md (Lead), documentation-specialist, and coordinator — all contributors need to know this Change: - Created .github/instructions/changelog.instructions.md - Covers which files to update, RST format, PR template checkbox, and when a changelog entry is required vs optional Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Context: - Error handling patterns appear in api-backward-compatibility-specialist and architecture-domain-specialist; relevant to any Python contributor Change: - Created .github/instructions/error-handling.instructions.md - Covers specific exception catching, forbidden broad catches, HTTP status codes, and get-or-create idempotency pattern Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Context: - 'organisation vs account' rule appears in documentation-developer-experience-specialist and AGENTS.md (Lead); applies to anyone touching UI templates or docs Change: - Created .github/instructions/ui-terminology.instructions.md - Covers organisation/account distinction, internal role names, Jinja2 safety, and toast vs inline alert choice Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Context: - data_key gotcha and schema parity requirements appear in both api-backward-compatibility-specialist and architecture-domain-specialist; ui-specialist also cross-checks API field keys in JS payloads Change: - Created .github/instructions/marshmallow-schemas.instructions.md - Covers data_key vs attribute name, code paths to audit on schema changes, schema parity between Input/BeliefsSearchConfigSchema, and API schema conventions Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Context: - Timezone requirements appear in data-time-semantics-specialist, architecture- domain-specialist, and documentation-specialist; any Python contribution may introduce naive datetime bugs Change: - Created .github/instructions/timezone-awareness.instructions.md - Covers creating aware datetimes, pandas localize/convert, nominal durations, DST edge cases, and docs example requirements Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Context: - Test conventions appear in test-specialist, tooling-ci-specialist, and AGENTS.md (Lead); relevant to any contributor writing or fixing tests Change: - Created .github/instructions/testing.instructions.md - Covers full-suite requirement, module-level validation, db vs fresh_db fixture selection, API test isolation, test design intent, and module-scoped state resets Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

…entions Context: - .github/instructions/ was created with 9 instruction files covering topics that appear in 2+ agent files (atomic commits, pre-commit, docstrings, changelog, error handling, UI terminology, Marshmallow, timezone, testing) Change: - Added a blockquote note after ## Role in each specialist agent file pointing agents and contributors to .github/instructions/ for shared conventions - Keeps agent files focused on domain-specific knowledge Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Context: - A new .github/instructions/ directory was created with 9 cross-cutting instruction files extracted from agent knowledge - Without documentation, future agents or contributors won't know the structure exists or how to extend it Change: - Added '### .github/instructions/ Structure' section under Domain Knowledge - Documents purpose, current file list with applyTo globs and topics, and a Coordinator checklist for when to create new instruction files Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

… structure Agent-Logs-Url: https://github.com/FlexMeasures/flexmeasures/sessions/bedb478c-beaf-40ea-be93-56f32672ca94 Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Flix6x

My main comment is that I expect the agent files to now need fewer instructions, so this PR should also be removing some lines.

Flix6x · 2026-05-23T09:02:49Z

+2. Add a YAML frontmatter block with `applyTo:` pointing to the relevant files.
+3. Write concise, actionable instructions in natural language Markdown.
+4. Update the table above.
+5. Reference the new file from the relevant agent files in `.github/agents/`.


Go through the agent files to remove sections that have been made redundant by the new file.

Flix6x · 2026-05-23T09:05:15Z

+## Entry format
+
+```rst
+* Brief description of the change, written for the intended audience. [see `PR #XXXX <https://www.github.com/FlexMeasures/flexmeasures/pull/XXXX>`_]


Follow the canonical formatting convention already present in the given changelog file (which might suddenly change or evolve in the future).

For instance, for the main changelog, we currently (!) prefer one sentence, without a period at the end of the sentence, abstracting away from technical details when possible, so you need to update this example.

API and CLI changelogs assume a slightly more technical audience and I think do use periods at the end. But again, the main rule is to follow the file's convention.

Flix6x · 2026-05-23T09:23:31Z

+
+- Internal refactoring with no user-visible effect
+- Test-only changes
+- Agent instruction updates


Small agent instruction updates

Flix6x · 2026-05-23T09:30:02Z

+## Run the full test suite
+
+After any code change, run the complete test suite — not just the tests for the module you changed:
+
+```bash
+uv sync --group test
+uv run poe test
+```
+
+Partial test runs are insufficient. FlexMeasures has interconnected systems where changes in one area affect others.


A full test run is only mandatory before finishing the session and requesting a review. Intermediate full test runs are encouraged when appropriate.

Flix6x · 2026-05-23T09:34:47Z

+start_time = datetime(2024, 1, 15, 10, 0, 0, tzinfo=timezone.utc)
+```
+
+Never show a naive `datetime(...)` call in user-facing documentation.


Nor in log statements.

Flix6x · 2026-05-23T09:38:03Z

+| Background job progress | `showToast("...", "info")` |
+| Persistent field description users need while interacting | `<div class="alert alert-info">` |
+
+Do not migrate inline `alert-info` divs showing persistent information to toasts — they would disappear before the user reads them.


would -> could

@Flix6x

…-terminology, and README Context: - PR #2198 review from @Flix6x Change: - changelog: follow canonical format (no period, section order feat/infra/fix, AI infra entry) - testing: clarify full suite is mandatory only before requesting review - timezone-awareness: add 'nor in log statements' - ui-terminology: 'would' -> 'could' - README: add step 6 to remove redundant agent sections after extraction Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Context: - PR #2198 review requested a changelog entry under Infrastructure / Support Change: - Added entry for cross-cutting Copilot instruction files in .github/instructions/ Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Context: - Cross-cutting conventions extracted to .github/instructions/ in PR #2198 Change: - Trim 'Must Run Pre-commit Hooks' to one-liner + pointer - Trim 'Must Add Changelog Entry' to one-liner + pointer - Trim 'Must Make Atomic Commits' + 'Commit Message Format' to one-liner + pointer - Trim 'Must Avoid Temporary Files' to one-liner + pointer - Trim 'Must Avoid Double Spaces' to one-liner + pointer - Trim 'UI Terminology' to one-liner + pointer - Trim session close checklist items to remove duplicated 'how-to' details Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

…ctions/ Context: - Cross-cutting conventions extracted to .github/instructions/ in PR #2198 Change: - Replace 'Docstring Style Rules' section with brief note + pointer to docstrings.instructions.md - Replace 'Running Pre-commit Hooks', 'Pre-commit Hooks in This Project', 'Fixing Linting Issues', 'Best Practices' with one-liner + pointer - Collapse 'Small Atomic Commits', 'Commit Message Format', 'Avoiding Temporary Files' into a single short section + pointer to atomic-commits.instructions.md Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Context: - Cross-cutting conventions extracted to .github/instructions/ in PR #2198 Change: - Collapse 'Atomic Commit Discipline' + 'No Temporary Analysis Files' into one-liner + pointer - Remove redundant 'Commit Message Format' section (now in atomic-commits.instructions.md) - Add pointer to pre-commit-hooks.instructions.md in dev environment section Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

…ng files) Context: - Cross-cutting conventions extracted to .github/instructions/ in PR #2198 Change: - api-backward-compatibility-specialist: trim 'Must Make Atomic Commits' to pointer - architecture-domain-specialist: collapse 'Atomic Commits' + 'No Analysis Files' to pointer - data-time-semantics-specialist: trim atomic commits list to pointer - documentation-developer-experience-specialist: trim atomic commits + planning files to pointer - performance-scalability-specialist: trim atomic commits list to pointer - tooling-ci-specialist: slim 'Pre-commit Hook Execution' to requirement + pointer Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Context: - Code review on PR #2198 flagged ambiguity in testing.instructions.md and changelog.instructions.md Change: - testing.instructions.md: clarify full suite is still mandatory at session close; targeted runs are only acceptable during active development - changelog.instructions.md: define 'small' agent instruction updates concretely - test-specialist.md: restore forbidden-docstring-pattern example Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Copilot AI and others added 12 commits May 22, 2026 22:36

instructions: add README documenting the .github/instructions/ folder…

8303564

… structure Agent-Logs-Url: https://github.com/FlexMeasures/flexmeasures/sessions/bedb478c-beaf-40ea-be93-56f32672ca94 Co-authored-by: Flix6x <30658763+Flix6x@users.noreply.github.com>

Copilot AI assigned Copilot and Flix6x May 22, 2026

Copilot created this pull request from a session on behalf of Flix6x May 22, 2026 22:48 View session

Copilot finished work on behalf of Flix6x May 22, 2026 22:48

Copilot AI requested a review from Flix6x May 22, 2026 22:48

Flix6x added the AI Infra label May 23, 2026

Flix6x requested changes May 23, 2026

View reviewed changes

Copilot started work on behalf of Flix6x May 23, 2026 09:39 View session

Copilot AI and others added 7 commits May 23, 2026 09:44

Copilot finished work on behalf of Flix6x May 23, 2026 09:51

Copilot AI requested a review from Flix6x May 23, 2026 09:51

Flix6x marked this pull request as ready for review May 24, 2026 08:42

Flix6x approved these changes May 24, 2026

View reviewed changes

Flix6x merged commit 4c2c87d into main May 24, 2026
12 checks passed

Flix6x deleted the copilot/create-instructions-folder branch May 24, 2026 08:45

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Create .github/instructions folder with cross-cutting topic instruction files#2198

Create .github/instructions folder with cross-cutting topic instruction files#2198
Flix6x merged 19 commits into
mainfrom
copilot/create-instructions-folder

Copilot AI commented May 22, 2026 •

edited

Loading

Uh oh!

Flix6x left a comment

Uh oh!

Flix6x May 23, 2026

Uh oh!

Flix6x May 23, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Flix6x May 23, 2026

Uh oh!

Flix6x May 23, 2026

Uh oh!

Flix6x May 23, 2026

Uh oh!

Flix6x May 23, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Copilot AI commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Flix6x left a comment

Choose a reason for hiding this comment

Uh oh!

Flix6x May 23, 2026

Choose a reason for hiding this comment

Uh oh!

Flix6x May 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Flix6x May 23, 2026

Choose a reason for hiding this comment

Uh oh!

Flix6x May 23, 2026

Choose a reason for hiding this comment

Uh oh!

Flix6x May 23, 2026

Choose a reason for hiding this comment

Uh oh!

Flix6x May 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented May 22, 2026 •

edited

Loading