From ae29dababd12d916e5f67a30935851eeb8fe704c Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Tue, 15 Sep 2026 14:53:51 +0200 Subject: [PATCH] Add AGENTS.md --- AGENTS.md | 146 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..4145223 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,146 @@ +# AGENT.md — Beffroi Reporting + +## Mission + +Beffroi Reporting is an integration and orchestration repository. + +It provides a convenient reproducible workspace combining: + + win-diagnostics + beffroi-reports + reportist + +It does NOT own their implementation. + +--- + +## Intended structure + + diagnostics/ → win-diagnostics submodule + reports/ → beffroi-reports submodule + reporter/ → reportist submodule + + scripts/ + Makefile + README.md + .gitmodules + +--- + +## Dependency direction + +This repository depends on the component repositories. + +Component repositories MUST NOT depend on this repository. + +Never introduce circular dependencies. + +--- + +## Submodules + +Use Git submodules to pin known-compatible revisions. + +Do not automatically follow remote branch HEAD. + +A checkout of a historical integration commit should identify the exact +versions of the tooling used at that point. + +--- + +## Bootstrap + +Provide a simple bootstrap process. + +For example: + + git clone --recursive ... + ./bootstrap.sh + +Bootstrap should: + +- initialize submodules; +- check dependencies; +- explain missing requirements; +- prepare the workspace where appropriate. + +Do not silently make invasive system modifications. + +--- + +## Workflow + +Aim for simple high-level operations. + +Examples: + + make collect + make analyse + make report INCIDENT=... + make render INCIDENT=... + make all INCIDENT=... + +The exact interface should follow actual workflows rather than these +examples mechanically. + +--- + +## Reproducibility + +A pinned integration revision should provide enough information to recreate +a historical report, subject to documented external/system dependencies. + +When updating a submodule, commit the version change intentionally. + +--- + +## Scope + +This repository may contain: + +- orchestration; +- bootstrap scripts; +- dependency checks; +- Makefiles; +- integration tests; +- documentation. + +It should NOT accumulate: + +- diagnostic rules; +- Typst templates; +- historical reports; +- duplicated component code. + +When substantial implementation appears here, determine which component +actually owns it. + +--- + +## Testing + +Provide at least one integration test using sanitized fixture data: + + diagnostic fixture + ↓ + analysis + ↓ + report data + ↓ + Reportist + ↓ + PDF + +This test verifies compatibility between pinned components. + +--- + +## Definition of success + +A developer wanting the complete Beffroi reporting environment can run: + + git clone --recursive + +and obtain a coherent set of known-compatible tools and reports. + +A developer wanting only one component should never need this repository. \ No newline at end of file